Thursday, November 13, 2008

Bob Martin's "Clean Code" Reviewed

I have gone through "Uncle Bob" Martin's new book, Clean Code,which is a lenthy presentation of rules that will help Java developers write better code. It's similar to Kent Beck's Implementation Patterns,except more code-fixated. Clean Code has some good points, but it contains several weaknesses that seem to have gone entirely by the reviewers on Amazon. So, here's the scoop.

First of all, it's well hidden, but the book is only partially written by Bob Martin. Many chapters are written by other consultants who work at Martin's company--many of whom I've never heard of. The one stand-out exception is Michael Feathers, whose chapter on error handling is one of the clearest in the book. I wish he had written more.

The main body consists primarily of explaining various coding rules that Martin calls heuristics and to which he assigns coded abbreviations for later reference. Alas, unlike patterns that have meaningful names as shortcuts, Martin chooses meaningless notations such as C2 and G26. So, "the function should do nothing but compacting[G30]" is a shortcut for the author, but a pain for the reader who has to cross-reference these references repeatedly to know what Martin is talking about.

Unlike Beck's book, there is no theoretical framework to Martin's prescriptions. The book is a series of examples from which he teases this rule and that. Because of this lack of framework there is a certain desultory aspect--the rules come in seemingly random order.

Some of them make you want to leap up and clap. For example, his rule that Javadoc should not contain HTML. How many times I've come to the same conclusion! I want to read comments in code easily. The small lift that HTML brings to Javadoc pages is not in anyway worth the difficulty it adds to the reading of comments in code. Bob Martin's one of the first persons I've encountered to say so unequivocally.

Other rules are good, but later contradicted. For example, Martin states that you should never leave commented-out code in place. [C5] As he points out, no one knows why it's commented out and so it remains in place forever. However, later on in an example of refactoring code per his own rules, Martin comments out large blocks of code without an explanation of how that squares with his earlier advice. (p.374)

Martin also uses questionable coding preferences. For example, all of his code uses indents of 2 columns. 2 columns? It makes every routine look like a solid chunk of code. It's clearly not a practice to be recommended.

A large portion of the book is an example of Martin refactoring someone else's code. He takes a long piece from an OSS project and proceeds to "improve" it. I found this section uncompelling. Perhaps because in Fowler's masterpiece Refactoring,each refactoring magically transforms the code. By comparison, Bob Martin's work seems journeyman-like. I didn't find the initial code interesting nor did I find Martin's cleaned-up version luminous. I was expecting a before-and-after scenario that would make me sit up and take notice. Instead, the exercise felt preachy, condescending at times, and ultimately not terribly convincing.

My last gripe addresses an inexcusable error: typos. There aren't many but they are frequent enough to be distracting. For example, Martin seemingly does not understand the difference between it's and its. (p. 272, p. 296, among others) And his code contains typos too. (p. 309). This carelessness erodes credibility. Books that preach quality should be flawless at the level of spelling and grammar.

Overall, I think some organizations can use several of Martin's heuristics as a means of boosting their in-house coding standards. But I doubt that careful coders will find much of value. Those developers will be better served by Beck's Implementation Patterns,which is based on principles and so communicates much more information in fewer words. Since my review of Beck's book, I must confess my admiration for it has deepened, and it's the volume I would recommend if you're looking to write cleaner code.


ed said...

More praise for implement patterns from me. My ability to communicate through code has gone through the roof as a result of reading it.

I've seen very negative reviews of this book. I think that comes from the fact that it's quite philosophical and requires effort on the part of the user to absorb and use the knowledge in it.

Itay Maman said...

I feel that writing code by following formulas that tell you that fragment x is better than y, does not make much sense (at least to me).

Patterns are different. They are always presented with a context, and a list of pros and cons. Beck's theoretical
framework provides the reader with the ability to weigh his decisions.

Formulas are imperative in nature. They imply that no decision should be involved. I think they quickly get the (unaware) programmer into troubles.

Anonymous said...

Bob Martin - What code I have seen from him was very poorly written.
We seems to be a great editor, but no much of a software engineer.
In his "XP Episode", he uses magic constants, poorly defines the problem and wrote pretty useless code from a real world perspective.
His testing very poor in this example as well as he did not test intermediate value.

Anonymous said...

Bob Martin is a sales man -- nothing more.

Philip Schwarz said...

One of Uncle Bob's chapters that stood out for me on a first pass was Chapter 6 - Objects and Data Structures.

Philip Schwarz said...

You said: Many chapters are written by other consultants who work at Martin's company--many of whom I've never heard of.

Presumably you have heard of Jeff Langr. I liked his chapters:Chapter 10 - Classes, and Chapter 12 Emergence.

He is the author of Java Style - Patterns for Implementation (highly recommended - based in part on Kent Beck's Smalltalk Best Practice Patterns), and Agile Java - Crafting Code with Test Driven Development

Andrew Binstock said...

@Philip Schwartz: Since I've reviewed Jeff's book on this blog, ( I think the odds are good. ;-)

Philip Schwarz said...

Thanks for pointing me to your review of Jeff Langr's book. I am new to your blog (although your name sounds familiar), and it looks like it will be worth looking at more of your posts.

On a slightly pedantic note, Clean Code has 17 chapters. A quick scan of the front page of each chapter tells me that Uncle Bob wrote 10 of them. So as you say, many chapters are written by other consultants who work at Martin's company. But why do you refer to these authors as people many of whom I've never heard of?: you say you know Feathers (1 chapter) and Langr (2 chapters), and I presume you know of Dean Wampler (1 chapter), who recently wrote Programming Scala, so that leaves only three authors who you don't know: Grenning, Schuchert, and Ottinger, who wrote just one chapter each.

P.S. I have just realised why your name sounds familiar: I first saw it in your post: Integration Watch: The zealots of agile