ryanmcdermott/clean-code-javascript

Clean code concepts in javascript. Promoting readable, reusable, and refactorable software in JavaScript

Summary

clean-code-javascript is a documentation-only repository that adapts Robert C. Martin's Clean Code book into JavaScript-specific guidance. The project ships no library, CLI, or package — the README itself is the deliverable, organized into 12 sections ranging from variables to comments. It is licensed under MIT and is meant to be read, not installed.

What it is useful for

The repository is a reference guide for engineers who write or review JavaScript. It works well for:

• Self-reviewing a pull request against a list of known code smells before requesting review.
• Onboarding engineers who are new to a team's JS conventions.
• Settling arguments in code review by pointing to a concrete Bad/Good example rather than opinion.
• Picking up JavaScript-specific idioms (default parameters, destructured arguments, spread-based cloning) in the context of code quality.

Each rule in the README is presented as a short explanation plus Bad and Good code blocks. For example, the "Use searchable names" section contrasts setTimeout(blastOff, 86400000) with extracting MILLISECONDS_PER_DAY = 60 * 60 * 24 * 1000. The "Avoid Side Effects" section shows replacing cart.push(item) with [...cart, item] so the input array isn't mutated. The "Avoid type-checking" section suggests polymorphism or TypeScript over instanceof chains.

How engineers can use it

There is no npm install step. The README is the product. A practical workflow:

1. Skim the table of contents (Variables, Functions, Objects and Data Structures, Classes, SOLID, Testing, Concurrency, Error Handling, Formatting, Comments) to locate a topic.
2. Open the corresponding section and compare the Bad/Good pairs against the code you are writing or reviewing.
3. Apply the pattern manually. Where the README recommends tooling, it points to existing projects: buddy.js and ESLint's no-magic-numbers rule for catching unnamed constants, and Immutable.js for managing immutable data.
4. For larger refactors, the SOLID section and the "Objects and Data Structures" section provide a checklist.

Three caveats the README calls out explicitly. First, the default-parameters example notes that defaults only apply to undefined, not to other falsy values like 0, '', null, or NaN. Second, the side-effects section warns that cloning large objects can hurt performance, and points to Immutable.js as a faster alternative. Third, the author states outright that the rules are guidelines, not absolute rules, so treat them as a starting point for discussion rather than enforced style. The repository is not archived, but it is a guide rather than maintained code, so check the README itself for any updates to the recommendations.