Dahlia Bock

Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin

My friend and colleague, Mark, lent me this book about 9 months ago and I’ve been slowly reading (ok, i’ve been slacking off for a few months) through it but I’ve finally made it to the end (well, sort of the end). I’ve been learning a lot of the things that were mentioned in the book over the course of the past few years working with my talented colleagues at ThoughtWorks but I think Uncle Bob (and friends) did a very good job of nailing down the practices that help developers write clean code. The book uses a lot of examples and shows a lot of code as well. I would recommend it for any developer who would want to improve themselves and learn how to write better and cleaner code.

What I learned

What is Clean Code? Uncle Bob asked some very well-known and experienced programmers what they thought and almost all of them agree that clean code should be straightforward, easily understandable and does ONE thing well.

Meaningful Names
The first step towards straightforward code is to have names that clearly reveal the intention of the author. That includes variable, method and class names. A name should answer all the big questions: why it exists, what it does, and how it is used. For example:
int d; // elapse time in days

The name d reveals nothing. We should choose a name that explicitly says what it represents:
int elapsedTimeInDays;

Functions
Functions should be small. They should do one thing. They should do it well. They should do it only.

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

The ideal number of arguments for a function is zero but one or two are acceptable. Three arguments should be avoided where possible, and more than three should require a very special justification else shouldn’t be used at all. Passing a boolean into a function is a bad practice. It immediately says that the function is doing more than one thing because if the flag is true, it does one thing, if it’s false, it does another.

Error handling should be done separately, because that’s already doing ONE thing.

Comments
I have always hated code inlined with comments (after of course I learned that my code should serve as the one and only documentation). It complicates the code because one would have to read the code AND the comments and if they don’t match up then it will cause more confusion.

Objects and Data Structures
This was an interesting chapter that outlined the difference between the two entities, which I thought were interchangeable. Objects hide their data behind abstractions and expose functions that operate on that data. Data structures expose their data and have no meaningful functions. They basically are virtual opposites.

This also highlights the differences between procedural and OO code.

Procedural code (code using data structures) makes it easy to add new functions without changing the existing data structures. OO code, on the other hand, makes it easy to add new classes without changing existing functions.

This is not to say that we never want to have data structures, but I think we just need to be careful when creating our “objects” and make sure that they aren’t data structures in sheep’s clothing.

Error Handling
I’ve been learning more about this topic recently, especially in one of my previous projects where error handling was of utmost importance since we were writing a shared services tool. It’s important to know when to throw exceptions and how to catch and handle them properly. Here are a few pointers from Michael Feathers:

1. Use exceptions rather than return codes
2. Write your try-catch-finally statement first
3. Use unchecked exceptions
4. Provide context with exceptions – to determine the source & location of an error
5. Define exception classes in terms of a caller’s needs
6. Don’t return null
7. Don’t pass null

Unit Tests
If there could only be one important thing to software development, testing would be it. But sadly a lot of developers treat tests as an after-thought, but really when we’re manually firing up the application and clicking a bunch of buttons to see if something was working, we could automate those steps and voila! we have a test!

The next step would be to drive the code from the test. The Three Laws of TDD (Test Driven Development):

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

Classes
I wrote a post about this chapter previously. You can read it here.

Systems
To stay clean a a higher level of abstraction, we need to be able to separate the construction of a system to it’s usage. There are a few ways that we can achieve that, the most primitive being moving all aspects of construction to the main method. Other ways include using factories and dependency injection.

Chapter 17 lists the code smells and heuristics that Uncle Bob has encountered over the years.

All in all a very useful book!