The latest book by Bob Martin, Clean
Code, is a cross between Steve McConnell’s Code Complete, Martin Fowler’s Refactoring,
Joshua Kerievsky’s Refactoring
to Patterns, with some tidbits of Kent Beck’s Implementation
Patterns. About a year ago I reviewed another book my Bob Martin, Agile Software Development, Principles, Patterns, and Practices which goes over
such important concepts as SRP, OCP, the Liskov Substitution Principle, IoC. You meet these usual suspects again in Clean Code, so it really helps to know them. You can read up on them here (PDF).
The good stuff
The book starts off with a philosophical discourse about what clean code is, the benefits of maintaining such code, its power to communicate, etc. The book tries to answer such tough perennial questions as, How do you name a method, class, variable, etc? I don’t know anyone who doesn’t struggle with this. The guidance is presented forcefully, with no excuses—take it or
leave it, and feel free to disagree (I did, at times).
Here are some key points that resonated with me the most:
Command query separation (Chapter 3)
This rule states that “every method should either be a command that performs an action, or a query that returns data to the caller, but not both.” Or, as the author puts it,
“Functions should either do something or answer something, but not both. Either your function should change the state of an object, or it should return some information about that object. Doing both often leads to confusion.”
For example, if a SetXxxx method on a class returns something, what is that return value? Can you easily tell? And why is there a return value at all? Is the method performing one too many actions? I’ve seen too many APIs which I had to look up in the docs because the signature was both a command and a query.
Have no side effects (Chapter 3)
Bob Martin puts it very succinctly: “Side effects are lies.” Indeed, side effects are insidious. “Uncle Bob” cites an example of a checkPassword method which is supposed to validate user credentials. Upon successful validation, though, the method also initializes a user session! Now, two problems: 1) the method is unfocused, and 2) the signature does not advertise the side effect (it other words, it’s lying).
Prefer exceptions to returning error codes (Chapters 3 and 7)
Here’s an interesting angle I’ve never thought of before:
“Returning error codes from command functions is a subtle violation of command query separation. It promotes commands being used as expressions in the predicates of if statements:
if (deletePage (page) == E_OK)
This does not suffer from verb/adjective confusion but does lead to deeply nested structures. When you return an error code, you create the problem that the caller must deal with the error immediately.”
I agree. Try/catch blocks can get ugly and clutter code, as “Uncle Bob” rightfully points out. Therefore it makes sense to extract code inside try/catch blocks into methods of their own.
As a bonus, Michael Feathers delivers an authoritative opinion against checked exceptions in Java.
Comments do not make up for bad code (Chapter 4)
Generally, your code should explain itself. The majority of comments are poisonous refuse and clutter. The discussion in this chapter goes above and beyond this soundbite.
The fluff
Bob Martin doesn’t seem to know when to stop. Clean Code has too much dead weight for my taste. His other book I mentioned was like that, too. The sample code is all Java. There is a chapter on JUnit internals, which I found boring to tears.
Then, there’s a chapter on step-by-step refactoring of a
SerialDate class. The entire listing is printed in the back of the book, in small font, with tests and everything. Now, come on! Have trouble sleeping? Here, read the listing.
Finally, there’s a chapter and an appendix on concurrency. These two have nothing to do with the scope of the book itself. It beats me why they have been included. Wait… Say what? The publisher wanted padding? That explains
it.
Conclusion
Overall, this is a good book. Poor typography, awful drawings, and typos aside, I’ve found some good ideas in there. The book is unfocused, though, so your mileage may vary.
