Set standards for writing readable and maintainable JavaScript
If fixing one function often requires touching other parts of the codebase, this guideline can help. It is a reference that adapts the principles from Robert C. Martin's 'Clean Code' to JavaScript syntax. It is not a style guide, but a guide on how to make code easier to read and fix.
From variable names to function structure
The guide proceeds in the order of variables, functions, objects, classes, SOLID principles, testing, concurrency, error handling, formatting, and comments. It recommends naming variables so their meaning is immediately clear and using the same vocabulary for the same kind of data. It advises splitting functions so they do only one thing and keeping arguments to two or fewer. It suggests avoiding conditionals where possible and using polymorphism instead of type checking. These principles are not strict rules, but reference points for teams to judge code quality.
Seeing the difference through specific code examples
Each item shows a 'bad example' and a 'good example' side by side.
- Meaningful names Variable or function names should immediately reveal the intent of the code. Using searchable names helps in finding code later.
- Single responsibility functions A function should do only one thing. Functions that do multiple things are hard to test and difficult to reuse.
- Minimizing side effects Functions should minimize side effects that change external state. When modifying objects or arrays, it is safer to create and return a copy.
Start with the first draft of the code
This guide does not claim that all principles must be followed unconditionally. Since software engineering is still an evolving field, these principles are merely guidelines derived from long experience. Code cannot be perfect from the start, and all code begins as a first draft. The process of refining incomplete parts through peer review is important. Knowing these principles does not immediately make you a better developer, but it does provide a standard for refining code.
Things to check before applying
This repository is useful when setting code review standards in JavaScript projects. It is worth referencing when you want to reduce friction caused by inconsistent code styles among team members. However, since not all principles are suitable for every situation, they should be applied selectively according to project scale and team culture. If using TypeScript, advice related to type checking can be adjusted to leverage TypeScript's static type features. This guide covers general JavaScript principles that are not dependent on specific frameworks or libraries, making it applicable in various environments.
