Clean Code

1. Clean code is readable, simple, and expressive

Clean code always looks like it was written by someone who cares.

Clarity is key. Clean code is characterized by its readability and simplicity. It should be easy for other programmers to understand, modify, and maintain. This involves using clear and meaningful names, keeping functions and classes small and focused, and organizing code in a logical manner.

Expressive code communicates intent. Clean code should clearly express the programmer's intent without the need for extensive comments. It achieves this through well-chosen names, small functions that do one thing well, and a clear overall structure. The code itself should tell a story, making it easy for readers to follow the logic and purpose of each component.

Continuous improvement is essential. Writing clean code is an ongoing process that requires constant attention and refactoring. Programmers should follow the Boy Scout Rule: "Leave the campground cleaner than you found it." This means always looking for opportunities to improve the code's clarity and structure, even in small ways, with each modification or addition.

2. Meaningful names enhance code clarity and maintainability

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used.

Choose descriptive names. Names should be self-explanatory and reveal the intent behind variables, functions, and classes. Avoid single-letter names, abbreviations, or cryptic codes that require mental mapping to understand their purpose.

Use naming conventions consistently. Adopt and stick to standard naming conventions for your programming language and team. This includes:

• CamelCase for class names (e.g., CustomerOrder)
• camelCase for variable and function names (e.g., totalAmount)
• ALL_CAPS for constants (e.g., MAX_SIZE)

Avoid disinformation and noise. Don't use names that could be misleading or confusing. For example, avoid using 'list' in a variable name if it's not actually a List. Also, avoid redundant or meaningless words in names, such as 'data' or 'info' when they don't add value.

3. Functions should be small, do one thing, and operate at a single level of abstraction

Functions should do one thing. They should do it well. They should do it only.

Keep functions small. Ideal functions should be no more than 20 lines long. This makes them easier to read, understand, and maintain. Smaller functions are also easier to name accurately, test, and reuse.

Single responsibility principle. Each function should have one clearly defined purpose. If a function is doing multiple things, it should be broken down into smaller, more focused functions. This improves readability and makes the code more modular and easier to modify.

Consistent abstraction level. Within a function, all operations should be at the same level of abstraction. Mixing high-level logic with low-level details makes functions harder to understand and maintain. Use the "Extract Method" refactoring technique to separate different levels of abstraction into distinct functions.

4. Comments should be minimal and truly necessary

The proper use of comments is to compensate for our failure to express ourselves in code.

Code should be self-explanatory. Well-written code with clear names and structure often eliminates the need for comments. Before adding a comment, consider if you can refactor the code to make its intent clearer.

Use comments judiciously. Good comments explain why something is done, not how it's done. They should provide context or clarification that can't be expressed in code alone. Types of useful comments include:

• Legal comments (copyright, licensing)
• Explanation of intent or algorithms
• Warnings of consequences
• TODO comments (sparingly used)

Avoid redundant or misleading comments. Don't write comments that merely restate what the code clearly says. Outdated or incorrect comments are worse than no comments at all, as they can mislead readers. Regularly review and update comments along with the code they describe.

5. Proper formatting improves code readability

Code formatting is about communication, and communication is the professional developer's first order of business.

Consistent style matters. Establish and follow a consistent formatting style across your codebase. This includes:

• Indentation
• Line breaks
• Placement of brackets
• Spacing around operators and keywords

Vertical formatting. Organize code vertically to enhance readability:

• Keep related concepts close together
• Separate unrelated concepts
• Declare variables close to their usage
• Place dependent functions near each other

Horizontal formatting. Keep lines reasonably short (usually 80-120 characters) to avoid the need for horizontal scrolling. Break long statements into multiple lines in a logical manner. Use white space to separate logical blocks within a line.

6. Objects and data structures serve different purposes

Objects hide their data behind abstractions and expose functions that operate on that data. Data structures expose their data and have no meaningful functions.

Objects vs. data structures. Objects encapsulate data and expose behavior through methods. They are good for adding new types (classes) without changing existing behavior. Data structures, on the other hand, expose data and have no significant behavior. They are good for adding new behaviors without changing existing data types.

Choose the right approach. Use objects when you want to add new types frequently but keep behaviors stable. Use data structures when you want to add new behaviors frequently but keep types stable. Understanding this distinction helps in designing more flexible and maintainable systems.

Law of Demeter. For objects, follow the Law of Demeter: a method should only call methods on:

• The object itself
• Its parameters
• Any objects it creates
• Its direct component objects
  This principle helps to reduce coupling between different parts of a system.

7. Error handling should be clean and informative

Error handling is important, but if it obscures logic, it's wrong.

Use exceptions rather than error codes. Exceptions provide a cleaner way to handle errors compared to traditional error codes. They separate error-handling logic from the main code, making both easier to understand and maintain.

Create informative error messages. Error messages should provide enough context to understand what went wrong and where. Include relevant details such as:

• What operation was being attempted
• What specific error occurred
• Any relevant values or state information

Write try-catch-finally statements first. When writing code that could throw exceptions, start by writing the try-catch-finally blocks. This helps ensure that the code is resilient to errors from the beginning and that error cases are properly considered.

8. Unit tests are crucial for maintaining clean code

Test code is just as important as production code.

Write tests first. Follow the practice of Test-Driven Development (TDD):

1. Write a failing test
2. Write the minimum code to pass the test
3. Refactor the code while keeping the test passing
   This approach ensures that your code is testable from the start and helps drive good design.

Keep tests clean. Apply the same standards of cleanliness to your test code as you do to your production code. Clean tests are:

• Readable
• Maintainable
• Trustworthy

Follow F.I.R.S.T principles for tests:

• Fast: Tests should run quickly
• Independent: Tests should not depend on each other
• Repeatable: Tests should be repeatable in any environment
• Self-Validating: Tests should have a boolean output (pass/fail)
• Timely: Tests should be written just before the production code

9. Classes should be small, focused, and follow the Single Responsibility Principle

The first rule of classes is that they should be small. The second rule of classes is that they should be smaller than that.

Keep classes focused. A class should have a single, well-defined responsibility. If you can't describe a class's purpose in about 25 words without using "and" or "or," it's probably doing too much.

Aim for high cohesion. Methods and variables within a class should be closely related and work together to fulfill the class's responsibility. Low cohesion often indicates that a class is trying to do too much and should be split.

Open-Closed Principle. Design classes to be open for extension but closed for modification. This often involves using abstractions and interfaces to allow new functionality to be added without changing existing code.

10. Concurrency requires careful design and implementation

Writing clean concurrent programs is hard—very hard.

Understand concurrency challenges. Concurrent programming introduces complexities such as:

• Race conditions
• Deadlocks
• Liveness issues
• Performance impacts

Keep concurrency-related code separate. Isolate code that deals with concurrency. This makes it easier to reason about, test, and maintain both the concurrent and non-concurrent parts of your system.

Use existing libraries and frameworks. Leverage well-tested concurrency libraries and frameworks (e.g., java.util.concurrent in Java) rather than trying to implement low-level concurrency control yourself. These tools have been optimized and thoroughly tested for common concurrency patterns.

Write thorough tests. Testing concurrent code is challenging but crucial. Write tests that:

• Create multiple threads
• Vary timing and scheduling
• Run many times to increase the chance of exposing intermittent issues
• Use tools like thread sanitizers and static analyzers to help identify potential concurrency bugs

Last updated: January 22, 2025