Skip to content

Clean Code Notes

Ch 1 - Introduction

Code should be readable and easy to see what it's doing.
Code is refined to fit these rules. Your first drafts won't fit these rules - you'll need to refactor. Have unit tests that cover the ugly code before you start refactoring.

Ch 2 - Naming

  • names should reveal intention
  • spell should be consistent
  • no disinformation - if something isn't a list don't call it a list (best not to use container types in names anyway)
  • distinctions should be meaningful - avoid noise words (a, the, data info, String, object, etc)
  • names should be pronouncable and searchable
  • no encoding (e.g. no hungarian notion such as m_)
  • no mental mapping (having to remember what a single letter var does)

Class Names

  • noun or noun phrase NOT verb
  • avoid non descriptive words like; Manager, Processor, Data or Info

Method Names

  • should be a verb or verb phrase name
  • javabean naming; accessors, mutators, setters should be named for their value and prefixed with get, set and is accordingly

  • constructors with overloaded static factory methods should have names that describe the argument (e.g. Complex.fromRealNumber(23.0f))

  • one word per concept (e.g pick one of load,read or get and stick with it)

  • don't use same word for different concepts
  • use Solution Domain names (e.g. comp sci terms, algorithm names, pattern names, etc)
  • Use Problem Domain names
  • add meaningful context e.g. state could be a number of things, addrState is more meaningful
  • don't add gratuitous context, its more junk you have to search through

Ch 3 - Functions

  • small (at most 20 lines)
  • indentation level, no more than 1 or 2
  • do one thing only, and do it well
  • either do something (Command), or answer something (Query)
  • error handling counts as one thing
  • one level of abstraction
  • have no side effects
  • use descriptive names
  • use the To Rule - read the function as a set of To paragraphs relating to the current level of abstraction
  • DON'T REPEAT YOURSELF

Switch statements

  • avoid where possible - use polymorphism instead
  • possible main area of use in foundation of abstract factories

Arguments

  • ideal number is 0
  • 1 or 2 is acceptable (but try to turn a 2 argument function into a 1 argument function where possible)
  • 3 should be avoided where possible, should never be more than 3 arguments
  • flag (boolean) arguments should be avoided (can split method into two methods)
  • variable arguments count as a single argument
  • avoid output arguments

Exceptions

  • preferred to return codes - separates error processing from valid code path
  • extract bodies of try and catch blocks into their own functions
  • returning error codes imply there is a class or enum in which the codes are defined. These are a dependency magnet whereas new exceptions are derivatives of existing exceptions - no need to recompile existing code (Open Closed Principle)

Structured Programming (Edsger Dijkstra's Rules of Structured Programming)

  • every function (and every block within a function) should have one entry and one exit point.