Clean Code

Robert C. Martin


A Handbook of Agile Software Craftsmanship

Chapter 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