Summary of 'Clean code' by Robert C. Martin

clean_code.md

What is Clean Code

• elegant and efficient
• does one thing well
• can easily be read, and enhanced by a developer other than its original author
• meaningful names
• minimal dependencies
• has unit and acceptance tests
• clean code always looks like it was written by someone who cares
• nothing obvious that you can do to make it better
• no duplication

Quotes

• "spending time keeping your code clean is not just cost effective; it’s a matter of professional survival"
• "Each function, each class, each module exposes a single-minded attitude that remains entirely undistracted, and unpolluted, by the surrounding details."
• "remember you are an author, writing for readers who will judge your effort"
• "The proper use of comments is to compensate for our failure to express ourself in code"
• "Writing tests leads to better designs"

Notes

• When constructors are overloaded, use static factory methods with names that describe the arguments. For example, Complex fulcrumPoint = Complex.FromRealNumber(23.0); is generally better than Complex fulcrumPoint = new Complex(23.0); Consider enforcing their use by making the corresponding constructors private.
• to know that a function is doing more than “one thing” is if you can extract another function from it with a name that is not merely a restatement of its implementation

Names rules

1. Choose descriptive and unambiguous names.
2. Make meaningful distinction.
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. Don't use flag arguments. Split method into several independent methods that can be called from the client without the flag.

Comments rules

1. Always try to explain yourself in code.
2. Don't be redundant.
3. Don't add obvious noise.
4. Don't use closing brace comments.
5. Don't comment out code. Just remove.
6. Use as explanation of intent.
7. Use as clarification of code.
8. Use as 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. Dependent functions should be close.
5. Similar functions should be close.
6. Place functions in the downward direction.
7. Keep lines short.
8. Use white space to associate related things and disassociate weakly related.
9. Don't break indentation.

Objects and data structures

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

• Objects expose behavior and hide data.
• Data structures expose data and have no significant behavior.

Error Handling

1. Write try-catch-finally first when wrtiting new code
2. Create informative error messages
3. Don’t return null (throws an exception or returns a special case object)
4. Don’t pass null
5. Wrap third-party API

Tests

1. Test one thing
2. Readable
3. Fast
4. Independent
5. Repeatable in every environement

Classes

1. Small
2. SRP (Single Responsibility Principle)
3. Should be open for extension but closed for modification
4. We should also be able to write a brief description of the class in about 25 words, without using the words “if”, “and”, “or”, or “but”
5. Small number of instance variables
6. Should depend upon abstractions, not on concrete details

Systems

1. Move all aspects of construction to "main" or equivalent
2. Use abstraction for dependencies
3. Use Dependency Injection (DI)
4. Use the simplest thing that can possibly work.

Emergence (the 4 rules)

1. Runs all the tests
2. Contains no duplication
3. Expresses the intent of the programmer
4. Minimizes the number of classes and methods

Code smells

1. Rigidity. The software is difficult to change. A small change causes a cascade of subsequent 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 involved risks and high effort.
4. Needless Complexity.
5. Needless Repetition.
6. Opacity. The code is hard to understand.

General rules

1. Follow standard conventions.
2. Keep it simple stupid. 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 root cause. Always look for 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 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 primitive type.
5. Avoid logical dependency. Don't write methods which works correctly depending on something else in the same class.
6. Avoid negative conditionals.