| name | clean-code |
| description | Use when writing or reviewing code for readability, maintainability, and expressiveness โ based on Robert C. Martin's "Clean Code."
USE FOR: naming conventions, function design, comment quality, formatting standards, error handling strategy, code readability improvements
DO NOT USE FOR: architecture layers (use clean-architecture), refactoring techniques (use refactoring), SOLID principles (use solid)
|
| license | MIT |
| metadata | {"displayName":"Clean Code","author":"Tyler-R-Kendrick"} |
| compatibility | claude, copilot, cursor |
| references | [{"title":"Clean Code โ Robert C. Martin (Book)","url":"https://www.oreilly.com/library/view/clean-code-a/9780136083238/"},{"title":"Robert C. Martin (Uncle Bob) โ Clean Coder","url":"https://blog.cleancoder.com/"}] |
Clean Code
Overview
Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin establishes that code is read far more often than it is written. Clean code is code that is easy to understand, easy to change, and does what the reader expects. It reads like well-written prose.
"Clean code always looks like it was written by someone who cares." โ Michael Feathers
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." โ Martin Fowler
Meaningful Names
Intention-Revealing Names
Names should answer: why it exists, what it does, and how it is used.
const d: number = 0;
const elapsedTimeInDays: number = 0;
Avoid Disinformation
Do not use names that imply a meaning different from the actual purpose.
const accountList: Map<string, Account> = new Map();
const accountsByName: Map<string, Account> = new Map();
Pronounceable Names
If you cannot pronounce a name, you cannot discuss it without sounding awkward.
const genymdhms: Date = new Date();
const generationTimestamp: Date = new Date();
Searchable Names
Single-letter names and numeric constants are hard to search for.
for (let i = 0; i < 34; i++) {
s += t[i] * 4 / 5;
}
const WORK_DAYS_PER_WEEK = 5;
const NUMBER_OF_TASKS = 34;
for (let taskIndex = 0; taskIndex < NUMBER_OF_TASKS; taskIndex++) {
realDaysPerIdealDay += taskEstimate[taskIndex] * DAYS_PER_IDEAL_DAY / WORK_DAYS_PER_WEEK;
}
Naming Conventions Summary
| Rule | Example (Bad) | Example (Good) |
|---|
| Use intention-revealing names | d | elapsedTimeInDays |
| Avoid disinformation | accountList (for a Map) | accountsByName |
| Make meaningful distinctions | a1, a2 | source, destination |
| Use pronounceable names | genymdhms | generationTimestamp |
| Use searchable names | 7 | MAX_CLASSES_PER_STUDENT |
| Avoid encodings / prefixes | m_name, IShapeFactory | name, ShapeFactory |
| Use nouns for classes | Manager, Processor, Data (vague) | Account, WikiPage, AddressParser |
| Use verbs for methods | data() | fetchData(), save(), deletePage() |
Functions
Small Functions
Functions should be small. Then they should be smaller than that. A function should do one thing, do it well, and do it only.
One Level of Abstraction
Statements within a function should all be at the same level of abstraction. Do not mix high-level policy with low-level detail.
function renderPage(data: PageData): string {
let html = "";
html += "<html><head><title>" + data.title + "</title></head>";
if (data.isTestPage) {
const setup = findInheritedPage("Setup");
html += setup.getContent();
}
html += data.content;
return html;
}
function renderPage(data: PageData): string {
const header = buildHeader(data.title);
const setupContent = includeSetupIfTestPage(data);
const body = buildBody(data.content);
return assembleHtml(header, setupContent, body);
}
Command-Query Separation
Functions should either do something (command) or answer something (query), but not both.
function set(attribute: string, value: string): boolean {
}
function attributeExists(attribute: string): boolean { }
function setAttribute(attribute: string, value: string): void { }
Function Arguments
The ideal number of arguments is zero (niladic), followed by one (monadic), then two (dyadic). Three arguments (triadic) should be avoided where possible. More than three requires very special justification.
function createMenu(title: string, body: string, buttonText: string, cancellable: boolean): Menu { }
interface MenuOptions {
title: string;
body: string;
buttonText: string;
cancellable: boolean;
}
function createMenu(options: MenuOptions): Menu { }
Avoid Side Effects
A function that promises to do one thing but also does other hidden things creates temporal coupling and order dependencies.
function checkPassword(userName: string, password: string): boolean {
const user = findUser(userName);
if (user && user.passwordMatches(password)) {
Session.initialize();
return true;
}
return false;
}
function checkPasswordAndInitializeSession(userName: string, password: string): boolean { }
Comments
Good Comments
- Legal comments: Copyright and license headers.
- Informative comments: Explain a regex pattern or complex algorithm.
- Explanation of intent: Why a decision was made, not what the code does.
- Warning comments: Alert others to consequences (e.g., "This test takes 10 minutes to run").
- TODO comments: Mark incomplete work with a consistent
TODO(author): convention.
- Amplification: Emphasize importance of something that might seem trivial.
Bad Comments
- Redundant comments: Restating what the code already says.
- Mandated comments: Javadoc for every function regardless of clarity.
- Journal comments: Change logs in the file (use version control instead).
- Noise comments:
/** Default constructor */ on a default constructor.
- Commented-out code: Delete it. Version control remembers.
- Position markers:
// ---- ACTIONS ---- banners (if you need them, the class is too large).
if (user.isActive) { }
if (user.requiresReauthentication) { }
Formatting
Vertical Formatting
- Newspaper metaphor: The name should tell you if you are in the right module. The top should give the high-level concepts. Detail increases as you move down.
- Vertical openness: Separate concepts with blank lines.
- Vertical density: Lines that are tightly related should appear close together.
- Vertical distance: Concepts that are closely related should be kept vertically close to each other. Variables should be declared as close to their usage as possible.
Horizontal Formatting
- Horizontal openness and density: Use spaces to associate strongly related things and separate weakly related things.
- Indentation: Never ignore the indentation. Even for short
if bodies, use braces and indent.
- Keep lines under 100-120 characters where practical.
Team Rules
A team of developers should agree upon a single formatting style. Consistency within a project is more important than any individual's preferred style. Use automated formatters (Prettier, ESLint, editorconfig) to enforce the rules without debate.
Error Handling
Use Exceptions Rather Than Return Codes
Return codes force the caller to check immediately and clutter the happy path.
function deletePage(page: Page): number {
if (page === null) return -1;
if (!page.canDelete()) return -2;
page.delete();
return 0;
}
function deletePage(page: Page): void {
if (!page) throw new ArgumentError("Page must not be null");
if (!page.canDelete()) throw new PermissionError("Page cannot be deleted");
page.delete();
}
Write Your Try-Catch-Finally First
Start with the try-catch-finally when writing code that could throw. This helps define scope and invariants.
Don't Return Null
Returning null forces every caller to add a null check. Instead, throw an exception or return a special-case object (Null Object pattern).
function getEmployee(id: string): Employee | null {
const record = db.find(id);
return record ? new Employee(record) : null;
}
function getEmployee(id: string): Employee {
const record = db.find(id);
if (!record) throw new EmployeeNotFoundError(id);
return new Employee(record);
}
function getEmployees(): Employee[] {
return db.findAll() ?? [];
}
Don't Pass Null
Passing null as an argument is even worse than returning it. It forces every function to start with null-checking boilerplate.
Objects and Data Structures
Data/Object Anti-Symmetry
- Objects hide their data behind abstractions and expose functions that operate on it.
- Data structures expose their data and have no meaningful functions.
These two approaches are complementary opposites:
- Procedural code (using data structures) makes it easy to add new functions without changing existing data structures.
- OO code (using objects) makes it easy to add new classes without changing existing functions.
interface Point {
x: number;
y: number;
}
function area(shape: Square): number { return shape.side * shape.side; }
function perimeter(shape: Square): number { return 4 * shape.side; }
interface Shape {
area(): number;
perimeter(): number;
}
Law of Demeter
A method f of class C should only call methods on:
C itself- Objects created by
f
- Objects passed as arguments to
f
- Objects held in instance variables of
C
const outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();
const outputDir = ctxt.getOutputDirectoryPath();
Clean Code Checklist
| Area | Question |
|---|
| Names | Does every name reveal intent? Could a new team member understand this without context? |
| Functions | Is every function under 20 lines? Does it do exactly one thing? |
| Arguments | Does any function take more than 3 arguments? |
| Comments | Does every comment explain why, not what? Are there commented-out blocks? |
| Formatting | Does the file read top-to-bottom like a newspaper article? |
| Error Handling | Are exceptions used instead of error codes? Is null ever returned or passed? |
| Duplication | Is there any copy-pasted logic? (Apply DRY) |
| Dead Code | Is there any code that is never executed? |
Best Practices
- Read code aloud. If it sounds awkward, the names or structure need work.
- Apply the Boy Scout Rule: clean up one thing every time you visit a file.
- Use automated linters and formatters to handle formatting debates mechanically.
- Treat tests as first-class citizens of clean code โ apply all the same naming, function, and formatting rules.
- Prefer polymorphism over switch/if-else chains when you find the same condition repeated.
- When you write a comment, first ask: "Can I make this code so clear that the comment is unnecessary?"
