Style Guide
In this document we expose and explain the guidelines and rules that we follow when we write, submit, share and publish code.
The guidelines are opinionated, as you should expect. The goal of these guidelines is to set a base for smooth communication and reduced friction when interacting with other developers. Guidelines for code style ensure a uniform style over the code base, so it is easier to switch between projects without the overhead of having to learn and understand a new style.
Code guidelines
Formatting
We use prettier to format code. Each project has a prettier configuration file. Code should be formatted before pushing and submitting a PR. CI checks verify that the code is formatted according to the code style. If code is not formatted accordingly, checks will fail and we will not review you PR.
You should run the formatter in your IDE on save.
If you do not want to run the formatter on save you should run it before you commit your code by using the command that is present in the package.json of the project: yarn prettier:write. this will format the code according to the code style for you. You can also check that the code is formatted by running yarn prettier:check.
Blank line at the end of file
You should configure your IDE or code editor to add a blank line at the end of your files. If you do not, the GitHub editor will mark the end of the file with a red circle. See this gist and the linked SO post for a justification of why you should end your files with a blank line.
Javascript and Typescript guidelines
In Javascript and Typescript files, indentation is one tab equals 2 spaces. We use spaces in our files. You should not input the spaces yourself. Configure your IDE or code editor to enter 2 spaces when you press tab. If you follow the formatting recommendations you should not even have to enter tabs yourself, the IDE or code editor should indent the code for you on save.
Submitting code for review
In this section we describe the steps you should take before submitting code in a PR (pull request) on GitHub.
Use conventional commits for your commits
Your commit messages should follow the conventional commits guidelines
Your PR title should be formatted according to the conventional commits guidelines
🚫 Example of a bad commit message:
done with work
✅ Example of a good commit message:
fix: issue related to username length
You can also add scopes to narrow down the field that your change is affecting:
fix(ui): improve display of username in dark theme
fix(test): reduce flaky websocket tests
The terms you should use are:
chore,build,refactor,style: for generic tasks related to project organisation or maintenance that do not affect the behavior of the code.fix: for bug fixes and patchesfeat: for new features and bigger changesdocs: for changes that improve documentation
Use conventional commits for your PR titles
Your PR titles should also follow the conventional commits (see the commit message section above) guidelines. We use automated tools to release software versions. If you do not format your PR titles with conventional commits your changes will not be picked up by the tool, so your work will effectively be invisible.
Review your changes before asking for reviews
Always review the set of changes you propose in a PR before adding reviewers.
When you ask for reviews you should make sure that you are aware of what code changes you are submitting. It is easy to forget a console.log(), or to commit some debugging code. While this is not the end of the world you should always respect the time and effort that others will take to review your code. Your code is the literal representation of your work. If you want to work well, you should always take the time to review your own code to ensure it follows the standards. This is exactly the same as proof-reading an important email before sending it, you don't want typos and badly written sentences to slip in, do you?
You can do this proof-reading when creating the PR in GitHub, as there is a nice summary of the changes presented at this time. You can also do it by opening the Files Changed tab after the PR has been created.
Submit a draft if you are unsure
If you are unsure about you changes, want to get feedback on your code from a co-worker, or simply think your work is not ready yet you should submit your PR as Draft. This will signal to the other developers that you are not done.
Link relevant issues
You should link relevant issues inside your PR body. Use closing keywords to auto-close issues when your PR is merged. See the GitHub documentation for more info.
Sharing code in markdown documents, messages etc
When sharing code with co-workers and developers alike please take the time to format it properly. Code that is not formatted is not easy to read and your co-worker will have a hard time de-cyphering what you intended to write.
For documents and comments where you can specify the language used
GitHub supports markdown nearly everywhere from issue and Pull Request body to review comments. You should always define the language of your code snippets. Define a code block with 3 backticks and add the language after the backticks on the first line, like so:
```ts
const hello = "world";
```
This will provide syntax highlighting and make the experience of reading code a lot more enjoyable for other people.
Read the Basics of Markdown formatting in the GitHub docs if you need a refresher of how to format certain things.
For messages (Slack etc)
Most instant messaging platforms allow you to use code blocks for sending multiline code in messages. In Slack it uses the same 3 backticks syntax as described in the markdown section, but does not support language highlighting.
Code present in GitHub
Use Github permalinks to reference code snippets in messages. Navigate to the source code that you want to send, click on the line number, click on the 3 dots and select "Copy permalink". This will create a link that you can send to your co-worker to improve communication about bits of code (there will even be a preview generated on the fly, how cool!).