‣ CleanCode


Clean Code: A Handbook of Agile Software Craftsmanship

(my comments, which I thought I'd write down as I go, if I remember and can be arsed. Probably not much interest to you unless you're reading it also)

Chapter 1: Clean Code

I involuntarily found myself nodding, uhhuhing and grimacing throughout the war stories and examples.

The detailed examination of a paragraph or two of text from such luminaries as Bjarn Stroustrup was a bit much for me. Far too much is read into their words, as if they were passed down from on high and we must interpret and re-interpret what they say. I particularly dislike the usage of 'my dictionary sez'. Does he really think they meant to imply all these secondary meanings? Given the emphasis elsewhere on 'good writing', I regard this is an indicator of lazy writing, as its often used as a way to fill space.

Chapter 2: Meaningful Names

I agree with most of this. I've always found class suffixes like "Data" and "Info" pointless. Putting "Data" on the end of a class name dissuades others from putting behaviour into the class and leads to lots of !FooData and !FooUtil classes. Your better off with just a Foo.

You do occasionally need classes which really are just structs. In languages like Java this is a manifestation of the need for multiple return values. In Scala, you'd just use a tuple, which you can destruct into its components. There must be other examples where a struct is probably legitimate, but I can't think of any right now.

Chapter 3: Functions

In principle, I agree with the use of small well-named functions. It's somewhat dubious to say they are "telling a story". As an aside, the repeated references to writing and storytelling remind me of the response to "Hackers and Painters". Programmers are not writers, artists or, to borrow an example from the response, auto-mechanics. They are programmers, pure and simple, and should be proud of it.

It can be worthwhile making analogies to other disciplines, but the ones used here are wrong. Programs are not stories. It might be better to say they have a linear, unfolding structure. However, not all stories are like that. I'd rather he justify that programs should be written in a certain way by referring to examples from real programs, and not through analogy. Just because they both be "written" doesn't mean they are the same. Is programming like sky-writing or peeing your name in snow?