Thoughts on „Clean Code“ from Robert C. Martin

I recently ordered some books from my project’s book recommendation list. This list is maintained by a few colleagues and contains many classics, but also some more hidden gems. Clean Code probably had to be on that list, and its not my first encounter. I skipped through the book already a few occasions before, but never really had the time and motivation to really digest its content. This time, this was different.

This is not a book review, but rather some personal notes and thoughts I gathered while reading it.

I particularly liked the first chapter, because it gathers quite some good statements and arguments why clean code really matters. Of course, everyone who ever development reasonably sized software themselves, know about the pros of clean code (as per whatever definition/guideline/philosophy). However, in daily close combat with management, customers and fellow developers, its not always easy to have the perfect argumentation at hand. So I always like to learn about new arguments objectively supporting subjective opinions.

The section „The Grand Redesign in the Sky“ describes very picturesque who the „its such a mess, lets do it from scratch“ often tends to (not) pan out in reality. That fits nicely to earlier thoughts and reads of mine regarding featuritis and the competition of legacy code maintainers and the new tiger team starting from scratch. Martin’s anecdote about such a competation taking more than 10 years was really eye-opening.

The next section talks about the attitude of developers needed to defend clean code:

Attitude

[…] Why does good code rot so quickly into bad code? We have lots of explanations for it. We complain that the requirements changed in ways that thwart the original design. We bemoan the schedules that were too tight to do things right. We blather about stupid managers and intolerant customers and useless marketing types and telephone sanitizers. But the fault, dear Dilbert, is not in our stars, but in ourselves. We are unprofessional.

This may be a bitter pill to swallow. How could this mess be our fault? What about the requirements? What about the schedule? What about the stupid managers and the useless marketing types? Don’t they bear some of the blame?

No. The managers and marketers look to us for the information they need to make promises and commitments; and even when they don’t look to us, we should not be shy about telling them what we think. The users look to us to validate the way the requirements will fit into the system. The project managers look to us to help work out the schedule. We are deeply complicit in the planning of the project and share a great deal of the responsibility for any failures; especially if those failures have to do with bad code!

Robert C. Martin: Clean Code, Pearson Education, 2009

I can very much relate to that code and – as a engineering manager and project manager with developer history – support confident developers defending their ground. Of course, there are more shades of grey, and I have experienced many arguments with developers who went too far in unconcrete demands for more time because of better quality. In my perspective, a proper discussion based on facts, figures and clear arguments from both sides – management and developers – yields the most best results, preferably as a compromise. But I get why Martin is triggering developers here explicitly.

Following are some statements from famous developers, you can read the first chapter of the book for free here. Then the actual content begins, where Martin describes one technique/rule/guideline after another, better naming, function design, commenting, formatting, error handling, testing etc. What follows are some refactorings of different sized open source code snippets, piece by piece, and in the end a list of „smells and heuristics“, an enumeration of indicators for bad code.

I have tried to apply the knowledge I gathered from reading this book in two ways:

1. I added phpmd – php mess detection – to my current pet project, with the clean code rules. Of course it can only identify a subset of bad code indicators, but its already a good start. There were some findings which I could quickly fix.
2. More practically, I started to refactor the code. E.g. I removed duplicate code, reduced function sizes and improved the error handling. Some of those improvements I already merged on master, but I am definetly not yet finished.

The worst part of the book was the example for „improved“ code given on pages 50ff. Maybe I didn’t get something essential, but this code is super-hard to read, understand, and totally cluttered with 1 to 3 line functions with awkward naming. I even suspected that this was kind of a trap/test to trigger the reader’s objection. Seems not. This made me also google for critique on the book, and this blog article also puts some good stances on it.

Can I recommend the book? Yes. I would take basically everything in it with a grain of salt, and there are some elements which I find „too much“. With that in mind, its a good motivation to critically reflect on own code and improve it iteratively.