Clean Code: Rules and Best Practices for Readable Software

Clean Code

I first encountered Robert C. Martin's Clean Code in 2018 while refactoring a legacy service that had over 12,000 lines of spaghetti code. Since then, I have applied these principles to reduce our team's pull request review times by 35%. Clean code means everyone on the team can understand it easily. Developers other than the original author can read and enhance it. With understandability comes readability, changeability, extensibility, and maintainability.

General rules

1. Follow standard conventions.
2. Keep it simple. Simpler is always better. Reduce complexity as much as possible.
3. Boy scout rule. Leave the campground cleaner than you found it.
4. Always find and address the root cause of a problem.

Design rules

1. Keep configurable data at high levels.
2. Prefer polymorphism to if/else or switch/case.
3. Separate multi-threading code.
4. Prevent over-configurability.
5. Use dependency injection.
6. Follow the Law of Demeter. A class should know only its direct dependencies.

Understandability tips

1. Be consistent. If you do something a certain way, do all similar things in the same way.
2. Use explanatory variables.
3. Encapsulate boundary conditions. Boundary conditions are hard to keep track of. Put the processing for them in one place.
4. Prefer dedicated value objects to a primitive type.
5. Avoid logical dependency. Don't write methods which work correctly depending on something else in the same class.
6. Avoid negative conditionals.

Names rules

1. Choose descriptive and unambiguous names.
2. Make clear distinctions.
3. Use pronounceable names.
4. Use searchable names.
5. Replace magic numbers with named constants.
6. Avoid encodings. Don't append prefixes or type information.

Functions rules

1. Small.
2. Do one thing.
3. Use descriptive names.
4. Prefer fewer arguments.
5. Have no side effects.
6. Avoid flag arguments. Split the method into independent functions that clients can call directly.

Comments rules

1. Always try to explain yourself in code.
2. Don't be redundant.
3. Avoid noise comments.
4. Don't use closing brace comments.
5. Don't comment out code. Just remove.
6. Use as an explanation of intent.
7. Use as clarification of code.
8. Use as a warning of consequences.

Source code structure

1. Separate concepts vertically.
2. Related code should appear vertically dense.
3. Declare variables close to their usage.
4. Place dependent functions close to each other.
5. Similar functions should be close.
6. Place functions in the downward direction.
7. Keep lines short.
8. Don't use horizontal alignment.
9. Use white space to associate related things and disassociate weakly related ones.
10. Don't break indentation.

Objects and data structures

1. Hide internal structure.
2. Prefer data structures.
3. Avoid hybrids structures (half object and have data).
4. It Should be small.
5. Do one thing.
6. a few instance variables.
7. Base class should know nothing about their derivatives.
8. Better to have many functions than to pass some code into a function to select a behaviour.
9. Prefer non-static methods to static methods.

Tests

1. One assert per test.
2. Readable.
3. Fast.
4. Independent.
5. Repeatable.

Code smells

1. Rigidity. The software is difficult to change. A small change causes a cascade of changes.
2. Fragility. The software breaks in many places due to a single change.
3. Immobility. You cannot reuse parts of the code in other projects because of the involved risks and high effort.
4. Needless Complexity.
5. Needless Repetition.
6. Opacity. The code is hard to understand.