Frontend: coding conventions and guidelines


(Chut Ko) #1

We need to create organized code which is easy to maintain and read. Current state is exactly the opposite. So here are guidelines which everyone who is working on Elvis frontend should follow:

Git conventions
From now, every commit should follow Conventional commits. Please read this and actually start using it. https://www.conventionalcommits.org/en/v1.0.0-beta.2/
This system will also create order in your development, because if you will follow the conventional commit message templates, you will have to decompose your work to several smaller tasks, each with specific focus. Also, from conventional commits, a CHANGELOG can be generated automatically.

Other notes:

  • Pull requests. Pushing into master is not allowed. You have to always create separate branch for your work and once finished, it will be pushed and code reviewed by others. Always. There is no chance unreviewed code will get into repository.
  • Do not include too many changes in one commit. Split your work into more commits so each commit message makes sense and brings specific result.
  • Do not push unfinished work or broken code

General coding conventions

  • Do not reinvent the wheel. Always search for pre-made libraries and repositories.
  • Recycle. Write code so it can be easily reused. Do not create one-time solutions.
  • If you repeat anything that has already been defined in code, refactor it so that it only ever has one representation in the codebase.
  • Do not create long files containing everything. Split code into reusable components.
  • Write comments!!! Please. Explain how your code works. Write TODOs if code behaviour can be improved.
  • Write code to be read. Do not write things just to work somehow. Its a way to hell
  • Debugging is twice as hard as writing the code in the first place. Write quality code and describe how it works in comments

Commenting

  • Explain design or architectural decisions that cannot be conveyed in code alone by adding comments to your code.
  • Be sure that in conjunction with writing code that adheres to these guidelines, someone can pick up your code and immediately understand it.
  • Be verbose with your comments but ensure your comments add something to the code, they don’t just repeat what is there. Make sure comments are kept up to date, if you change something that has been commented, ensure you up date the comment as well
  • If code needs extensive commenting, can it be refactored to make it less complex / easier to understand?
  • You focus on why rather than how - unless your code is too complex, it should be self documenting
  • Don’t leave commented out chunks of code in the codebase. It makes the code look unfinished, and can be confusing for other developers. If you are commenting chunk of code, write also why.

Follow the principles of ‘Keep It Simple, Stupid’ (KISS); hard to read or obfuscated code is difficult to maintain and debug. Don’t be too clever; write code to be read.

Ember
Write Ember code with Ember coding guidelines in mind:


Resources:


https://handbook.imarc.com/frontend
https://help.github.com/en/articles/setting-guidelines-for-repository-contributors