Clean Code
Robert C. Martin
2008
A Handbook of Agile Software CraftsmanshipChapter 1 - Clean Code
Clean Code means caring
It should be elegant, optimal, and follow a clear logic
It includes tests
Making code easy to read is time well spent since re-reading code actually represents most of the writing process
Chapter 2 - Meaningful Names
Use descriptive, unambiguous, and consistent naming
Chapter 3 - Functions
'Functions should do one thing. They should do it well. They should do it only.'
One level of abstraction per function
No argument or one argument only: arguments require a lot of conceptual power and make exhaustive testing difficult
Arguments should be input, no output
When transforming the input, return it as output
No side effects
Separate command and queries
Prefer exceptions to returning error codes (actually mixing command and queries)
Error handling functions should only handle errors: they start with try and end up with the catch/finally block
Extract try/catch blocks
No goto, of course
This should be a refining process: no one can be expected to come up with a perfect syntax in the first draft
Chapter 4 - Comments
'Don't comment bad code - rewrite it'
'Comments are always failures'
Explication of intent/decision
Amplify an important detail
No paraphrasing comment
Chapter 5 - Formatting
Vertical density/distance should be meaningful
Local variables are declared at the top of each function (since functions are short)
Instance variable are declared at the top of each class, of course
For dependant functions, the caller should be above the callee
Line length below basic screen width (~100)
No column alignment
No short statement collapsing
Chapter 6 - Objects and Data Structures
Abstract structures sharing only intensive properties should always be preferred to concrete structures disclosing all extensive properties
Law of Demeter - Objects should hide their internal structure from external modules
Avoid train wrecks
Chapter 7 - Error Handling
Use Exceptions rather than Return Codes
Use unchecked exception to respect the Open/Closed Principle
Wrap third-party APIs
Use Special Case Pattern so that client code does not have to deal with exceptional behaviour
'Don't return null. Don't pass null.'
Chapter 8 - Boundaries
Use wrapping to protect against external API changes
Chapter 9 - Unit Tests
'Without tests every change is a possible bug'
Clean tests are as much important as clean code
Build-Operate-Check-Decorator pattern
One assert per test. One concept per test.
FIRST: Fast - Independent - Repeatable - Self-Validating - Timely
Chapter 10 - Classes
Public static constants, then private static variables, then private instance variables
Classes should be small (Single Responsibility Principle) - the Single Responsibility Principle states that every module or class should have responsibility over a single part of the functionality provided by the software, and that responsibility should be entirely encapsulated by the class
Maintain class cohesion to keep classes small (by extracting cohesive function groups as independant classes)
Chapter 11 - Systems
Chapter 12 - Emergence
Clean code checklist:
- runs all the tests
- contains no duplication
- expresses the intent of the programmer
- minimises the number of classes and methods (low priority versus other three)
Use standard pattern names (Command and Visitor)
Chapter 17 - Smells and Heuristics
Avoid long import lists by using wildcards
Tests - use a coverage tool