I just finished reading 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.
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 excellent 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.)
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.
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.
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:
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.
There’s just one person behind this website; if this article was helpful (or interesting), I’d appreciate it if you’d share it. Thanks, Al.
One more to the list:
"A real architect spends time coding, spends time with programmers in iterations so that they understands the mess they made!"
"Longer the scope of the variable, the loger the name of it should be. "