Clean Code Review

This post is a review of the book Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin (and others).

Clean Code opens with the premise that it is not a "feel good", easy reading book, reading the book is not a passive activity but one that involves understanding and critiquing lots of code and thinking about the problems within it yourself before being presented with the authors' opinions of the problems. Whilst I agree with the justification given, I did "feel good" after reading the book, mainly because I had learnt so much and had been given an enthusiasm to get straight to my laptop and start refactoring my code.

For most people, Clean Code will tell you that you're doing something or many things wrong when you're programming. It provides well thought out arguments about why it's wrong to do things in certain ways and offers "cleaner" alternatives. Even if you disagree with the authors on a particular point, the reasoning given by the authors will help you realise when to adapt your approach. Many of the things pointed out as being wrong may well seem obvious yet, after reading the book I started noticing that these problems are everywhere, in my own code, in open-source projects and in advice on forums.

Here are some of the points that I found most interesting or were new to me:

• Try to check-in code a little cleaner than when you checked it out
• Don't encode the container type into the name (in case you change container type...)
• Don't slightly alter a variable name just to satisfy the compiler
• Don't add useless additional words to variable names, eg amount in moneyAmount, info in customerInfo
• Make functions small and then smaller (though more about in this in my upcoming review of Code Complete)
• Blocks within if, else and while statements should be small, preferably just a function call
• "If a function does only those steps that are one level below the stated name of the function, then the function is doing one thing" (functions should only do "one thing"!)
• The fewer arguments a function has, the better, be suspicious of functions with 3 or more arguments
• Encode name of arguments into function eg assertExpectedEqualsActual
• If functions are small, then multiple exit points are OK.
• Use good naming to make comments redundant and then get rid of the comments
• Hierarchically structure functions below the function they are called from
• Don't return null, removes the need for the clutter of null checking statements
• Create interfaces over 3rd party code to protect yourself from changes
• Write tests to discover and document how 3rd party APIs work
• 3 Laws of TDD:
  1. You may not write production code until you've written a failing unit test
  2. You may not write more of a unit test than is sufficient to fail (not compiling is failing)
  3. You may not write more production code than is sufficient to pass the currently failing test
• "Test code is just as important as production code". The only difference between the two should be that test code can be inefficient
• Try to minimise the number of asserts in a test (can be achieved by writing custom asserts as long as you can give the custom assert a sensible name)
• Classes should have one responsibility - only one thing changing should cause them to change
• Can separate classes from a large class by grouping by which member variables they act on
• "To write clean code, you must first write dirty code and then clean it"

The last point there is I think particularly important, the authors give the OK to writing code that gets the job done and the tests passing first, and then cleaning it up piece by piece until you have clean code.

The book is somewhat focused on Java, which manifests itself in various ways such as there being a chapter on JUnit and also some of the smells in the book are dependent on having the extensive IDE support that is available for Java. For example, the authors discourage the use of naming conventions to make member variables distinct from local and argument variables, saying that this distinction should be handled by the IDE. Which may not be the case if you're using a newer, less supported language. You certainly shouldn't let this put you off, the amount of general information in the book far outweighs any Java specific information and you can still gain insight from the reasoning behind any Java specific thought.

Possibly the most important part of the book is the collection of code "smells" and heuristics and the end of the book. These are things to look out for in code with explanations of why each one is bad and options on how to make it cleaner. This collection of smells with explanations makes the book invaluable as a reference. Clean Code has made me a better programmer and with repeated checking of it's list of smells, it will continue to do so. It has also driven up my enthusiasm for writing really good code, so I'd definitely recommend it to anyway who spends much time programming. If you're a programmer by profession, then your colleagues will definitely also be glad that you've read it.

Link to buy the book on Amazon.com