Skip to main content

General

Coding standards that apply to any app, language or framework.

Coding​

Give everything a single responsibility​

Every file, class or function should do one thing, and do it well. If it does more than one thing, split your code. Keep your files, classes and functions small. It's okay to have files with just one single line of code.

Exceptions apart, code smells if:

  • a file is longer than ~120 lines of code;
  • a component has more than 5 inputs/outputs (combined).

Don't repeat yourself (DRY)​

  • Do not copy code to another place. If you need to reuse (pieces) of code, extract that code to a class, function or other reusable format and store it in a shared place. This could also mean creating a component to reuse repetitive pieces of HTML code.
  • Do not use magic strings. If you use a string more than once, create a constant, enum, type etc.
  • PHPStorm offers this feature to analyze your duplicates: Analyze duplicates | PhpStorm

Use pure functions​

Keep functions pure as much as possible. That means, avoid manipulating values of input arguments or referencing/manipulating global state. This makes your function more predictable, easier to test and scalable.

Don’t implement deprecated features​

Don't use deprecated features if you can avoid them. If you refactor code that uses any deprecated features, you must rewrite the code to avoid using that deprecated feature.

Check browser support​

When using (new or experimental) features, first check if browser support is acceptable for your target audience. If not, make sure to use a polyfill to fix any issues.

Can I use provides up-to-date browser support tables for support of front-end web technologies on desktop and mobile web browsers.

Apply progressive enhancement​

Provide a baseline of essential functionality to as many users as possible, but best possible experience only to users of the most modern browsers.

For example, if you want to implement notifications using the browser’s Push Notifications API, you could leverage progressive enhancement using feature detection to enrich the experience of users that use browsers with support for this feature.

Dependencies​

Keep your dependencies up to date​

Always keep your dependencies up to date. Upgrade to the latest versions for your dependencies regularly.

Depend on 3rd parties as little as possible​

Only install 3rd party dependencies if you can not write the code easily yourself. We have recommendations for each type of project in these docs.

Use native features as much as possible​

If a technology provides a feature natively that solves a problem you need to solve, use the native feature instead of an external library.

Documentation​

Add documentation to project root​

Each frontend project requires at least a README.md file in the root folder. This Markdown file explains:

  • the purpose of the project;
  • the structure/outline of the project files;
  • how to make the project run locally;
  • (optional) how to deploy the project;
  • contact information for any questions or issues.

Add documentation to features​

You can consider adding a README.md file to your feature modules, reusable components etc., if it’s more than what you would write in JSDoc annotations.

Keep README.md files up to date​

Always check if code you contribute to a project should be documented, either in its own readme file, or the project’s readme file. Pay special attention to things like:

  • commands that need to be run to get/keep things working;
  • environment variables that are needed for local testing.
Include vital information

Don't make your team mates wonder what is needed to get things running. The general documentation should ALWAYS have ALL the information needed to run a project!

Writing comments​

Don’t fix bad code with comments​

Before you write a comment, check if it fixes bad code. Using comments to make badly written code more understandable is not okay. Rewrite your code to be as clear as possible.

Write comments to clarify code​

There are some cases when comments are useful:

  • Explain why something works the way it does. When someone asks why something is done a certain way, for example a colleague in a code review, consider adding a comment to the code instead of replying in the review.
  • Add comments to things that took you some time to figure out.
  • Add explanations to regex. They are weird and unclear.
  • If you see parts of an application that need refactoring, you should add a // @TODO: comment that explains what should be done.

Update comments after code changes​

If you refactor code with comments, afterwards check if comments are still applicable. Don't leave commented out code in your commits. If you do, add a comment explaining why it was left there.

Add annotations to public APIs​

  • Each service or class should be annotated, explaining the purpose of the class.
  • Each public property or method should be annotated, explaining the purpose of the property or method. If you can, include an example, preferably the most used implementation.

Git​

To keep our repositories, branches and commits consistent, please follow these standards.

Use consistent branch names​

Always use kebab-case for branch names, and use a prefix. We use the following branch prefixes:

  • fix for bug fix branches
  • feature for new feature branches
  • refactor for code refactoring

Branch names should adhere to the following structure:

  • [prefix]/[ticket-id]
  • [prefix]/[some-descriptive-name]

The slash / groups branches inside their corresponding category. The ticket ID makes it easy to search for, or find, the correct branch.

Use conventional commits​

Use the Conventional Commits v1.0 specification for commit messages.

  • If possible, include the ID of the corresponding ticket in the commit message.
  • Only commit one feature at a time.

An example of how to set up a pre-commit hook to check your commit message formatting before committing can be found soon in this repository.