Coding Guidelines

Clarity, not cleverness

Your code will be read and refactored by other team members. Strive for clarity, not shortcuts or clever hacks that are ultimately fragile and hard to understand.

Code less, assemble more

“The best code is no code” -- Caio Almeida

Every new line of code introduces bugs. We want to maximize our reuse of existing code instead of writing new code. Typically, reuse will come from existing modules; that’s why it’s essential to have good knowledge of available modules and to be able to “assemble” a required feature from existing modules, instead of creating it from scratch.

Choose the “right” 3rd party module

Do some research on existing modules that can help your implementation. Ask the team if they can advise on a good module. Proceed with a GitHub or Web search. When you identify potential modules, use the following list of criteria to guide your choice:

• Read the module LICENSE - if it’s not there or it’s not open source, don’t proceed!
• Read the module README - if it’s not there or it’s not clear, proceed at your own risk!
• Run the module tests - if there are no tests, proceed at your own risk!
• Check its dependencies, don’t proceed!
• Don’t use a React component that has React as a dependency (as opposed to a peerDependency which is OK)
• Assess module activity:
  • If not updated in years, proceed at your own risk!
  • If issues are not being answered or never getting closed, proceed at your own risk!
  • Bonus points for module roadmap
• Economy > Features: When choosing among candidates, choose the simplest module that fulfills your requirements. Simplicity/economy includes:
  • API to use is easy to understand
  • Code size is not unnecessarily big
  • Features surface is not significantly larger than features needed
• Assess performance if needed: In some cases, the module is required to perform a potentially long computation on a large data set. In this case, review performance benchmarks and comparisons for the candidate modules. If none are published, consider running simple benchmarks yourself to avoid selecting modules that are clearly inefficient (at this stage, order-of-magnitude comparisons are probably sufficient).
• If the third party module contains a bug or requires a change in order to fulfill our needs, we encourage developers to:
  • Fork the module
  • Make the required changes
  • Submit a PR to the official repository
  • Use the fork until the change is merged to the official repository
  • In case of JavaScript modules, publish the module to an npmjs account to reference it in your code
  • Delete the fork and use the official repository again when the fix or feature is there
  • Read more about dependencies

Follow coding conventions

Follow the conventions of the file that you are editing. If you’re starting a new file, follow the conventions of the surrounding files.

Clearly mark TODOs

If you’re implementing a function but don’t have the time/knowledge to implement as thoroughly as you’d like, add a TODO or FIXME comment clearly explaining what should be done. This will help the team enhance the code when time comes for refactoring. Sometimes it’s also important to file a ticket on Mantis so we keep it in our radar.

Document code borrowing

If you’re using code found on Stack Overflow or elsewhere on the Internet, add a comment with the URL of the page where you found the code. This will help other developers understand the logic of your implementation.

Document your commits

When committing new code, include both the corresponding issue number in GitHub and a short description of the new code going in, for example: “Description #1234”. Also add notes on testing your new code or fixes.

Don’t commit sensitive data to a public repo

Most of our repos are public, and we intend to keep it this way. This means we need to be extra careful not to include secrets in our repos.

Examples of sensitive data: Usernames, passwords, internal domain names, API keys / tokens / secrets

If you do commit secrets by mistake, it’s not enough to delete them from a repo, because history is kept by Git. Instead, you need to erase the history of the file - which is a tricky and disruptive process.

Learn about good programming practices

http://en.wikipedia.org/wiki/Category:Programming_principles

Frontend coding practices

• Use makeStyles instead of inline styles or styled components
• Use React Hooks when implementing new components
• Latest version of Material UI components
• No derived state
• Implement PropTypes for your components
• Use latest version of Relay when implementing new components
• Prefer <FormattedMessage /> over props.intl.formatMessage
• Use the plural format when formatting text with counts of objects - think of special cases such as zero objects.
• Please fix the warnings that appear on the browser console