How to Code (by someone who doesn't know how to)

how-to-code.md

How to Code

Your project MUST be set up before you proceed with working on it, otherwise it'll come back to bite you in the butt later.

Contents

• Terminology

• From Scratch

  • Package Scripts
  • Prettier
  • Setting up Git

• Configuring Typescript

• Adding Dependencies

• Running your Code

  • Using ts-node
  • Using tsc

• Working with Git

  • Pushing newly made changes
  • Terminology
    • Repository
    • Remote
    • Branch
    • Commit
  • Commands
    • git pull
    • git status
    • git add
    • git commit
    • git push
    • git checkout

Terminology

This guide uses a number of different terms throughout its length - here are a few of the most commonly used ones.

Project Root

This is defined as the directory in which all of your projects are contained.

If you store your projects in a directory called Projects, and you have a project named SkyeIsGay, the project root is Projects/SkyeIsGay.

This directory contains:

• package.json
• .gitignore
• src/

From Scratch

You're working with node, so you need to initialize a node project. Node requires packages, which you will install using the package manager Yarn.

Yarn spits out all the required dependancies into a file called package.json. THIS IS THE MOST IMPORTANT FILE IN YOUR PROJECT. If this is configured incorrectly, nothing will work.a

Luckily, Yarn provides a command to make this process easier:

$ yarn init

This creates the package.json file with some default values, and gets you set up for adding more dependancies.

Package Scripts

Within your package.json, you can specify a "scripts" field. This lets Yarn run locally installed scripts, such as ts-node or tsc.

In general, scripts are run using yarn <name>.

For example, the sample below will run the ts-node src command when you execute yarn start.

{
    "scripts": {
        "start": "ts-node src"
    }
}

Prettier

Prettier is a code formatter that keeps everything nice and tidy, as well as consistent. A formatter is incredibly important to configure correctly, otherwise your codebase will be utter garbage.

When using Prettier, your editor should have its default formatter set to prettier, as well as Format on Save turned on.A

Prettier is configured using the .prettierrc file, found in the project root. Like tsconfig.json, this is a JSON file (despite not having the extension), and you should take some care over ensuring it's set up correctly.

Here is a base configuration you can use.

{
    "tabWidth": 4,
    "useTabs": false,
    "semi": true,
    "arrowParens": "always"
}

Setting up Git

You can find more information on Git in its dedicated section.

If you're going to be working with git, then you need to initialize a new repository in this directory:

$ git init

The .gitignore file is required when working with Git. This file prevents you from uploading files that don't need to be in Git, like the megabytes of dependancies that aren't your projects.

Copy this file and paste it into a new .gitignore file in the root of your project.

The .gitignore is simply a load of paths not to include in the repository. You can include files, directories, globs, and more, and git will ignore them for you.

Read more on the gitignore here.

Configuring TypeScript

Perhaps the second most important part of setting up a project, TypeScript must be configured correctly in order for your project to work.

TypeScript is configured using the tsconfig.json file. For now, I wouldn't worry too much about what all of it does. Instead, I suggest copying the JSON below:

{
    "compilerOptions": {
        "target": "ESNext",
        "module": "CommonJS",

        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true
    },

    "include": ["src"]
}

This is a good boilerplate tsconfig.json and will do pretty much everything you need it to do.

Adding Dependancies

Dependancies are added using Yarn. Yarn provides one command which will install all of the dependancies you need.

$ yarn add <package1> <package2> <...>

This will install the given packages into your node_modules directory, so you can use them in your code.

Because not everyone uses TypeScript, not all projects come with types prebundled. Luckily, the @types repository provides types for pretty much every project you need.

Type dependancies should be installed as devDependancies instead of regular dependancies. All you need to do to mark them as such is add the -D flag to your command.

$ yarn add -D @types/some-package

Removing dependancies

It's as easy as it sounds:

$ yarn remove <package>

Note: You don't need to specify the -D flag if it's a devDependancy. Yarn will uninstall your package just fine.

Running your Code

Since we're using TypeScript, regular node won't work when trying to execute our code.

There are two ways to fix this:

• ts-node
• tsc

Using ts-node

ts-node is a wrapper around TypeScript and its compiler, letting you execute your .ts code as regular .js code.

The syntax is identical to node:

$ ts-node <file>

Using tsc

tsc, or the TypeScript Compiler translates your .ts code into .js files. Usually, this should only be used when you're building for production, but it can be helpful for locating bugs within your code.

This command, when run in the project root, builds your current source and spits it out into wherever is specified in tsconfig.json.

$ tsc --project tsconfig.json

Working with Git

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

Git is used for whenever you want to keep track of the changes you make to a project, and is absolutely necessary when working with multiple people at once.

Pushing newly made changes

This is one of the most important parts of Git, so I'll show you how this is done before telling you how it works:

$ git add .
$ git commit -m "some description of the changes"
$ git push

Terminology

Repository

A repository is a directory where all your code is stored. It stores the history, and future (if it exists) of changes you made to code.

Every developer working on the project has their own local copy of the repository, and makes changes to theirs, before "pushing" them to the remote repository.

All commands executed within Git must be executed inside this directory. Generally, it is a good idea to have your project root as the repository.

Note: Never have more than one repository in a given directory - this will confuse Git and break stuff.

Local

The local repository is your copy, on your hard drive, on your computer, which you will be working directly on.

Any changes made to it must be "pushed" to the remote repository.

Remote

A remote is a externally-hosted version of your repository.

Generally, this is a website like GitHub, and it holds the version of the code you and all your developer friends will be working on simultaneously.

Note Remotes always have a name - the most common one you see is origin.

Branch

Branches are effectively a pointer to a snapshot of your changes. When you want to add a new feature or fix a bug — no matter how big or how small — you should create a new branch to encapsulate your changes.

Any one repository can have an unlimited number of branches, and Git provides a number of tools for switching between them.

There are a number of key branches you should use:

• stable - this is the latest stable version of your code, and what you should be running for everyone to use.
• master - this is the development branch of your code, where you push updates before merging them into stable.

Commit

A commit is a snapshot of the state of a repository at any one point in time. Commits represent points in your code history that you can rewind or fast-forward to if something goes wrong, or you wish to make a change.

Note: It's advisable to commit as often as possible, although within a reasonable extent. In general, I'd say your average commit shoul be about 100 lines long.

Commands

To interact with your repository, there are a wide variety of commands you can use.

git pull

This command pulls new commits from the remote repository to your local copy.

Note: You must not have any outstanding changes made when you try to pull - if you do, Git will complain.A

# Pull the latest changes.
$ git pull

git status

This command shows you your current outstanding changes that you haven't yet committed to your local repository.

Files not added to the next commit to be made will show up in red, and files that have show up in green.

git add

This command is used to add files to your next commit.

# Add all changes in your current directory to the next commit.
$ git add .

# Add changes in the specific file to your next commit
$ git add skye-is-gay.ts

git commit

This command is used to create a commit on your current branc from your outstanding changes.

Note: Always include a message with your commit. This lets other developers know what your commit does.

# Add outstanding changes and commit them.
$ git add .
$ git commit -m "Added some new stuff"

git push

This command pushes any new commits you have made to your local repository to the remote.

When pushing to a new branch (see below), you need to run the command like so:

$ git push -u origin <branch_name>

This tells git where to push the branch to on the remote.

git checkout

This command is used to revert or switch to a different branch of your repository. This is incredibly useful and you should use this more often.

Switching between existing branches is easy:

$ git checkout <branch>

Note: Any un-commited changes you have will follow you into your new branch. It's advisable to commit these to your previous branch, unless you are intending to switch branches with these files.

Switing to a new branch is also easy.

$ git checkout -b <new_branch>