Quotes from Clean Code

Back in 2013 I read the book Clean Code by Robert C. Martin, and in an effort to keep that book alive with me a little while longer, I decided to make my own “Cliffs Notes” version of the book on this page. One of my favorite notes from below is that a language named LOGO used the keyword to in the same way that Scala uses def, so a method named double would be defined as to double... instead of def double..., which seems like it would help developers name methods better.

Writing clean code

Here's a short collection of quotes from Clean Code, with my comments added after each quote.

“Later equals never.”

In our youth we always said, "I'll clean up the code later", but of course we never did. "Later equals never" is known as LeBlanc's Law.

“The only way to make the deadline — the only way to go fast — is to keep the code as clean as possible at all times.”

The only thing I'd change in that quote is to say, “the only way to constantly go fast.” You can go fast in the short term by taking shortcuts, but not in the long term.

“Clean code always looks like it was written by someone who cares.”

This was written by Michael Feathers. This quote reflects something I stress during training and mentoring sessions. Programmers need to think of themselves as craftsmen, and take pride in their work. Maybe customers can't see your work, but other developers certainly can, and you should take pride in writing crisp, clear code that other programmers can easily read and comprehend.

“Leave the campground cleaner than the way you found it.”

This is similar to the previous quote. I didn't know it, but this is a Boy Scouts of America rule/slogan. In Alaska they have the exact same statement about using the Public Use Cabins here, leave it in better shape than the way you found it.

“The ratio of time spent reading (code) versus writing is well over 10 to 1 ... (therefore) making it easy to read makes it easier to write.”

This was something I never really thought about before, but Uncle Bob Martin makes a very convincing case that when we're working on software projects with other developers, we're constantly trying to understand existing code when writing new code, to see how our new code should work and fit into the system.

“You know you are working on clean code when each routine you read turns out to be pretty much what you expected. You can call it beautiful code when the code also makes it look like the language was made for the problem.”

That quote comes from Ward Cunningham (inventor of the Wiki, inventor of Fit, co-inventor of eXtreme Programming, and much more), who seems to be one of the greatest programmers of our time. I haven't met him yet, but whenever I read his writing, he blows me away. That statement alone sold me on this book.

Make your code read like a story

The following quote begins what I think is the best section of the book:

“The LOGO language used the keyword TO in the same way that Ruby and Python use def.”

I never worked with LOGO, but the author begins describing how code should read like sentences in a book. Later he adds:

“Make the code read like a top-down set of TO paragraphs.”

Eventually he takes these thoughts to this conclusion:

“Master programmers think of systems as stories to be told rather than programs to be written.”

For me, that's a very powerful phrase. I suspect you probably need to read his book to really understand what he's saying here, but if you read the section where he writes about the LOGO TO statements, he makes his point very well:

“In order to make sure our functions are doing 'one thing', we need to make sure that the statements within the function are all at the same level of abstraction.”

This is another great line, and something I hadn't thought of consciously before. If code in a function is doing one thing at a high level of abstraction, another thing at a medium level, and another at a low level, it's going to be very hard to read, whether you consciously know why, or not. (This really is an excellent observation.)

Functions

Here's a nice starter quote about functions:

“The first rule of functions is that they should be small.”

As you've probably read elsewhere, a function should do one thing, and only one thing.

“Functions should do something, or answer something, but not both.”

As he states, a function should change the state of an object, or return some information about that object, but not both. I've run into many functions over the years where a function was named "setSomething", and then when I looked at the source for that function, I found that it did several other things besides the "set" it claimed to do.

“Methods should have verb or phrase names.”

Very true. I'm always naming methods "handleXYZ", "getXYZ", "calculateXYZ", and so on, trying to use verbs and action names.

“One way to know that a function is doing more than 'one thing' is if you can extract another function from it with a name that is not merely a restatement of its implementation.”

This is another great observation that I've never thought about consciously. Many times you can look at a function and obviously know it's trying to accomplish more than one thing, but other times you look at a function and all you can tell is that it's wrong ... it doesn't seem right for some reason, but you can't put your finger on it.

This "rule", along with the other statement about function statements all being at the same level of abstraction, are very nice observations.

Comments

Here's a great statement about comments in source code:

“Every time you write a comment, you should grimace and feel the failure of your ability of expression.”

Like many experienced programmers, the author has been burned by out of date comments, useless comments, and so on, and has come to the conclusion many others have: Most comments are not needed, and if you feel the need to write a comment, you should consider rewriting your code to make it more readable.

try/catch blocks

One of my pet peeves about try/catch statements is how complicated they make code. The author expresses my sentiments exactly, then states:

"It is better to extract the bodies of the try and catch blocks out info functions of their own."

This is a clever technique that can be used to make try/catch blocks as readable as they can be.

Clean Code, and the Principles of OOD

In this book, Mr. Martin also writes about things like:

• The Single Responsibility Principle
• The Open Closed Principle
• The Liskov Substitution Principle

and much more. You can find information on each of these topics on his website:

• Principles of OOD

Clean Code, by Robert C. Martin

I hope these notes have been helpful, and I also hope they encourage you to buy Clean Code. It's an easy read, with many more helpful nuggets that can help to make you the best programmer you can be.