Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin Series)

by Robert C. Martin

good software practice requires such discipline: focus, presence of mind, and thinking.

Code, without tests, is not clean. No matter how elegant it is, no matter how readable and accessible, if it hath not tests, it be unclean.

There is no escape from this logic. You cannot write code if you cannot read the surrounding code. The code you are trying to write today will be hard or easy to write depending on how hard or easy the surrounding code is to read. So if you want to go fast, if you want to get done quickly, if you want your code to be easy to write, make it easy to read.

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.

When constructors are overloaded, use static factory methods with names that describe the arguments.

Say what you mean. Mean what you say.

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.

FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY.

“You know you are working on clean code when each routine turns out to be pretty much what you expected.”

The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.

Flag arguments are ugly. Passing a boolean into a function is a truly terrible practice.

In general output arguments should be avoided. If your function must change the state of something, have it change the state of its owning object.

Functions should either do something or answer something, but not both.

The proper use of comments is to compensate for our failure to express ourself in code.

So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.

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

Truth can only be found in one place: the code. Only the code can truly tell you what it does. It is the only source of truly accurate information. Therefore, though comments are sometimes necessary, we will expend significant energy to minimize them.

Replace the temptation to create noise with the determination to clean your code. You’ll find it makes you a better and happier programmer.

A team of developers should agree upon a single formatting style, and then every member of that team should use that style. We want the software to have a consistent style. We don’t want it to appear to have been written by a bunch of disagreeing individuals.

There is a well-known heuristic called the Law of Demeter2 that says a module should not know about the innards of the objects it manipulates.

What price? The price of checked exceptions is an Open/Closed Principle1 violation. If you throw a checked exception from a method in your code and the catch is three levels above, you must declare that exception in the signature of each method between you and the catch. This means that a change at a low level of the software can force signature changes on many higher levels. The changed modules must be rebuilt and redeployed, even though nothing they care about changed.

When we return null, we are essentially creating work for ourselves and foisting problems upon our callers. All it takes is one missing null check to send an application spinning out of control.

Returning null from methods is bad, but passing null into methods is worse.

Good software designs accommodate change without huge investments and rework. When we use code that is out of our control, special care must be taken to protect our investment and make sure future change is not too costly.

First Law You may not write production code until you have written a failing unit test. Second Law You may not write more of a unit test than is sufficient to fail, and not compiling is failing. Third Law You may not write more production code than is sufficient to pass the currently failing test.

What makes a clean test? Three things. Readability, readability, and readability.

What makes tests readable? The same thing that makes all code readable: clarity, simplicity, and density of expression. In a test you want to say a lot with as few expressions as possible.