Coding Guidelines
We use spaces, not tabs.
#
Names- Use PascalCase for
type
names - Use PascalCase for
enum
values - Use camelCase for
function
andmethod
names - Use camelCase for
property
names andlocal variables
- Use UPPER_SNAKE_CASE for
true constants
(hardcoded string or env variable) - Use whole words in names when possible
#
CommentsUse JSDoc style comments for functions
, interfaces
, enums
, and classes
#
StyleOur style guide is very similar to Airbnb's Javascript Style Guide, apart from a few minor modifications. Notably, spaces should be included inside parentheses and brackets.
#
LintingMany of our repos contain an ESLint configuration file. You can run ESLint on any file or directory by running npx eslint yourfile.js
in a terminal or command prompt.
It is recommended to integrate ESLint with your editor so you can receive linter suggestions as you type. We recommend VSCode's ESLint extension.
In addition to linting, code will automatically be checked by GitHub Actions for style.
#
Commit MessagesOur git commit messages consist of three sections separated by blank lines in the following format:
- Type and subject is mandatory. Scope is optionally added in parentheses. See one of our repo's commit history for examples.
- Use the footer to reference GitHub issues, e.g.
Close #128
orRelated #128
. We use this for tracking issues.
#
TypeA majority of our commits tend to be one of the following:
- feat: Changes that introduce a new feature or enhancement; Always an addition or improvement.
- fix: Changes related to unexpected behavior; Usually bug related, but also for correcting typos/content.
- perf: Changes that improve performance.
- refactor: Changes that don't alter behavior, don't add features/enhancements, don't affect performance, and don't change anything for the user.
note
Typos are always mistakes, and therefore type fix. Additions/enhancements to content are type feat.
We have some target level types:
- build: Changes to our build system or external dependencies (e.g. with scopes: gulp, broccoli, npm)
- ci: Changes to our CI configuration files and scripts (e.g. with scopes: Circle, BrowserStack, SauceLabs)
- docs: Changes to our documentation
- test: Changes to our tests; Adding missing tests or correcting existing tests
And, the last type:
- style: Changes to code that are superficial and do not affect anything in a meaningful way (e.g. white-space, formatting, missing semi-colons)
#
ScopeMost types should have a scopes, as defined by the repo. See the CONTRIBUTING.md
file in a project repo for scopes.
Some types do not require scopes:
style
,test
, andrefactor
changes to multiple scopes (e.g.style: add missing semicolons
).docs
changes (e.g.docs: fix typo in readme
).
#
SubjectWe begin our subjects in lowercase and remove any trailing punctuation (e.g. period or exclamation mark).
The subject line must be no more than 72 characters. If you're unable to succinctly summarize what you've done, then perhaps too many changes are being committed at once. Aim for smaller commits which can be explained better.
Our subjects are written imperatively. The imperative is the same as if giving a command or instruction. It can be easily tested by substituting the subject for blank in the line "this commit will FILL IN THE BLANK". Examples: refactor, update, show, hide, add, remove, allow, prevent, open, close.
#
BodyCode is generally self-explanatory. Not every commit requires a body. Some changes are so simple that no further explanation is necessary. Even complex code should have comments for explanations.
Focus on using the body to explain why you made the changes. Explain how it worked before the change, why it required changing, and why you resolved it the way you did.
If the subject is the command, then the body is the purpose.
#
FooterIf your commit relates to a GitHub issue, then use the footer to link it (e.g. "Related #128"). If your commit would close a GitHub issue when merged, then use the footer to automate it (e.g. "Close #128"). One commit should almost never reference multiple issues, but if need be the commands can be comma-separated (e.g. "Close #128, Close #64, Related #32").
#
RevertWhen reverting single commits, modify the header of the commit being reverted by beginning it with revert:
and use the body of the commit to reference the SHA hash of the commit being reverted.
Example commit with SHA abc123
Example of reverting commit with SHA abc123