Thoughts on "Clean Code"

I just finished reading Clean Code: A handbook of agile software craftsmanship, by Robert C. Martin. It’s a highly regarded book and contains many useful ideas; I have started refactoring some aspects of Tuskfish based on things I learned from it. This will include improving names, shortening and splitting up some of the larger functions into smaller logical units, converting static methods to be non-static (big job), replacing magic numbers with named constants and so on. Mainly better style and to some extent better structure.

The book and code examples are Java-oriented, so for a PHP developer some parts are not relevant. As you may expect when anyone mentions ‘Java’, it also has a heavy and somewhat dogmatic (I'm being kind here) object-oriented bent. Most of the useful material lies in the first 40% of the book, thereafter it starts laying on the Java syntax and you’ll need quite a lot of patience to slog through the code.

There were some aspects I didn’t agree with. For example the author argues that if your functions and variables are well-named the code becomes self-describing and so a lot of comments can be removed. While this is true to some extent, if you’re sharing your code with people who are learning to program or that aren’t experts or that are of varying skill levels, even mundane comments can be useful. 

I tend to leave a block-level narrative of what’s going on throughout my code with occasional explanations of design decisions. The IDE draws the eye to these, making it easy to browse and follow the logic in plain English without having to analyse the gritty detail. Breaking a thirty-line function into two fifteen-line functions just for “purity of design” reasons does not always make code easier to understand or maintain. There are diminishing returns on such things.

I got the Kindle edition of book, but I'd suggest to get the paper version if you can as you'll probably want to flip back and forth through code samples, and there's a good chance you'll want to use it as a reference book.

TLDR: It’s a good book with valuable advice that is quite likely to improve your code. Definitely worth a read but, but it is rather opinionated in places, and some of it is not relevant to PHP developers (Java).