Skip to content

Style Guide

Jump to bottom
Sam Zhou edited this page Mar 20, 2019 · 6 revisions

General Rules

The repo has already been setup with some linter config and style guides. They should be automatically installed when you are installing the dependencies.

You should configure your IDE so that it will warn you when it's violated. You should not ignore those linter warnings. You are expected to follow the guides given by the linters and only commit code that passes the linter checks.

When you have doubts about why certain linting rules exist, you should first search online to understand it's rationale. If you are unsure about how to make the linter happy, please ask another team member.

However, sometimes you may need to suppress some linter checks. In those circumstances, you should document the reason why you must suppress these checks. It should only be occasionally used.

Backend

Always follow the PEP 8 style guide.

IDE Integration:

  • PyCharm: PEP 8 linting enabled by default.
  • VSCode: link
  • Atom: link

Frontend

ESLint

Always follow the airbnb JavaScript style guide. We already have the ESLint config setup in the repo.

ESLint IDE Integration:

  • JetBrains family: IntelliJ, WebStorm
  • VSCode: link Please ensure you have these options inside your VSCode Settings:
{
    ...
    "eslint.enable": true,
    "eslint.packageManager": "yarn",
    "eslint.validate": [{
            "language": "javascript",
            "autoFix": true
        },
        {
            "language": "javascriptreact",
            "autoFix": true
        },
        {
            "language": "typescript",
            "autoFix": true
        },
        {
            "language": "typescriptreact",
            "autoFix": true
        },
    ],
    "eslint.autoFixOnSave": true,
    "eslint.alwaysShowStatus": true,
    ...
}

TypeScript

Besides ESLint, we also use TypeScript to statically type-check our frontend code. Since JavaScript is a dynamic language with many surprises and our frontend code is inherently complex, this is a must. You are expected to add type annotations to your React components and pass the TypeScript static type checker tsc. This will be enforced by Circle CI when it builds your commits.

TypeScript should be automatically installed in node_modules/ when you are installing frontend dependencies. The config of TypeScript is listed here.

To run TypeScript locally to type-check your code, you can run yarn tsc. TypeScript can provide reliable type-based auto-completion service for your IDEs, so you should properly configure it.

TypeScript IDE Integration:

Documentation

You should document all your code.

For each frontend components and functions, you should give sufficient information to enable the user of the component/function to completely understand what needs to be passed in. If the type signature and the component/function name is always obvious what's going on, you don't need to repeat it in the docs.

Clone this wiki locally