Guide · Open source
How to use clean-code-javascript: a practical guide to readable JavaScript
Updated · written with AI from the project's own documentation and checked against our catalogue data
clean-code-javascript is an MIT-licensed written guide, adapted from Robert C. Martin's book Clean Code, that explains how to write JavaScript that is easier to read, reuse and change. It is aimed at developers who already know the basics and want concrete refactoring examples. By the end of this guide you will know how the guide is organized, how to read its Bad and Good examples, and how to use it in your own code or in team reviews.
clean-code-javascriptryanmcdermott/clean-code-javascript · ★ 94.7k · MIT Install options & downloads Quick start
- 1Open the guide. Read the README on GitHub or clone the repository with git clone to read it locally.
- 2Pick a topic. Start with Variables or Functions, or choose the section that matches the problem you are fixing.
- 3Compare Bad and Good. Read each Bad example, predict what is wrong, then check the Good example to confirm the principle.
- 4Apply one rule at a time. Refactor a small piece of your own JavaScript using a single rule, such as one function doing one thing.
- 5Discuss in review. Use the rule names as shared vocabulary when reviewing pull requests with your team.
What is clean-code-javascript and who is it for?
The project is a set of guidelines rather than a strict style guide. The README says that not every principle has to be strictly followed, and that even fewer will be universally agreed upon. It treats the guidelines as a touchstone for judging the quality of the JavaScript you and your team produce.
It suits developers who want to improve the readability of their JavaScript, teams who need shared review guidelines for code quality, and students learning software design principles in JavaScript. It is less suited to beginners, because many examples assume familiarity with the language.
- Good fit: developers who already write JavaScript and want refactoring examples
- Good fit: teams that want a shared vocabulary for code review
- Not a fit: anyone who wants a linter or automatic formatter
- Not a fit: anyone who needs strict, universally agreed rules
How do you read the guide?
The guide is organized by topic: Introduction, Variables, Functions, Objects and Data Structures, Classes, SOLID, Testing, Concurrency, Error Handling, Formatting, Comments and Translation. Each topic is split into short rules, and each rule shows a Bad example followed by a Good example.
Read the Bad example first and try to say what is wrong with it before reading the Good version. The comparison is the point of the guide, so the gap between the two snippets is where you learn the principle.
- Start with Variables and Functions, which are the most concrete topics
- Use the 'back to top' links to jump between sections
- Treat each rule as a prompt for a code review question, not a command
Get a local copy of the guide
The guide is read online on GitHub. If you want to read it offline or keep a copy for your team wiki, clone the repository with the command below. No other prerequisites are listed in the source.
git clone https://github.com/ryanmcdermott/clean-code-javascriptApply the variable and naming rules
The Variables section covers meaningful and pronounceable names, consistent vocabulary, searchable names, explanatory variables and avoiding mental mapping. For example, the guide replaces a cryptic name like yyyymmdstr with currentDate, and replaces the magic number 86400000 with a named constant such as MILLISECONDS_PER_DAY.
The guide also points out that default parameters only apply to undefined arguments. Values such as '', false, null, 0 and NaN will not be replaced by a default value.
- Replace unexplained literals with named constants
- Avoid repeating the object name inside property names, such as carColor on a Car object
- Use default parameters where they fit, and remember the undefined-only rule
function createMicrobrewery(name = "Hipster Brew Co.") {
// ...
}Apply the function rules
The Functions section recommends two or fewer arguments, and says that three should be avoided where possible. When a function needs many inputs, the guide suggests passing a single object and destructuring it, which makes the expected properties clear in the signature.
The guide's most emphasised rule is that functions should do one thing. It also asks that function names say what they do and that each function stay at one level of abstraction.
- Count the arguments in each function you review
- Split functions that do more than one action
- Name functions after the action they perform, such as addMonthToDate
function createMenu({ title, body, buttonText, cancellable }) {
// ...
}Work through the later topics
Beyond variables and functions, the README covers Objects and Data Structures, Classes, SOLID, Testing, Concurrency, Error Handling, Formatting and Comments. Read these in order when you have time, or jump to the topic your team is currently arguing about in code review.
The guide mentions tools such as buddy.js and ESLint for finding unnamed constants. It does not replace those tools, so use them alongside the guide if you want automated checks.
- Use the table of contents to pick a topic
- Use the guide as a shared checklist in pull requests
- Pair it with a linter if you need automatic enforcement
What people use it for
- Refactoring a long JavaScript function into smaller functions that each do one thing
- Agreeing on naming conventions for a team codebase during code review
- Teaching software design principles to students using concrete Bad and Good examples
- Replacing a function with many positional arguments with a single destructured options object
Frequently asked questions
Is clean-code-javascript free to use?
Yes. The project is licensed under the MIT licence, as stated in the project information. You can read it online or clone it with git.
How do I install clean-code-javascript?
There is nothing to install in the usual sense, because it is a written guide. The README suggests cloning the repository with git clone https://github.com/ryanmcdermott/clean-code-javascript if you want a local copy.
What are the requirements for clean-code-javascript?
The source does not list any prerequisites. However, many examples assume you already know JavaScript, so beginners may find it hard to follow.
Is clean-code-javascript a linter or formatter?
No. It is a set of written guidelines. The README mentions tools like ESLint only in passing, so you will need a separate tool for automatic checks.
How does clean-code-javascript compare to Airbnb or Google JavaScript style guides?
Style guides such as Airbnb JavaScript Style Guide and Google JavaScript Style Guide are usually rule sets for formatting and conventions. This guide focuses on readability, reuse and refactoring principles, and says its guidance is not strict or universally agreed.
Are the principles in clean-code-javascript mandatory?
No. The README states that not every principle has to be strictly followed, and that even fewer will be universally agreed upon. Treat them as guidelines for review.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use clean-code-javascript if you already write JavaScript and want concrete Bad and Good refactoring examples to share with your team. Pick a style guide, a linter or a formatter instead if you need enforced rules or automatic formatting, or if you are just starting out with the language.
Install options & downloads