mgroves

Well, I've finished Clean Code, but my blogging each chapter is too far behind at this point. However, I thought I would throw out a quick summary blog, and recommend the book one last time before I shelve Clean Code as a blog topic for now.

Clean Code is a book that every developer should read, agree with it or not. It should probably be the textbook for a course in Computer Science (or Computer Programming, whatever) degrees. It teaches a lot of little rules and heuristics for writing clean, maintainable, good code, but ultimately it teaches a process. Care about your code, care about variable names, class names, formatting, small methods, and single responsibility. Your code won't always be perfect; it won't be in the Smithsonian; but it can always be improved, a little bit at a time.

After reading this book, I find myself asking better questions about the code I'm writing. Should this method be here? Should it be named something better? Should it be broken out into smaller methods? Is there any way I can reduce or remove the repetition? While I may not always have the experience and judgment to answer these questions completely and correctly, I think getting in the mindset of always interrogating and improving my code is a good place to be.

I've also been privileged to help organize a great group of developers in Columbus area to form a book club for Clean Code this year. The book provided an excellent starting place and guide for discussions, arguments, and stories about coding. I know that I have learned a great deal more about applying the concepts in Clean Code by just talking to smart, experienced developers. So, not only do I recommend the book, I recommend discussing the book.

“Comments are not like Schindler’s List. They are not ‘pure good.’ Indeed, comments are, at best, a necessary evil.”

I have gotten into some heated discussion recently about comments, mainly because I agree with the above quote from Clean Code.  It’s possible that my code isn’t expressive enough.  And by possible, I mean very likely.  However, that doesn’t mean I need more comments: it means I need to write better code.  That’s an opinion, but an opinion that’s validated by chapter 4 of Clean Code.

Here are a couple of points that were brought up in defense of commenting, and commenting often:

• Incompetent programmers: i.e. developers who don’t know basic syntax or basic design patterns
• Non-native English speakers: keywords, classes, frameworks, documentation, variable names, etc. have an English bias.

Those aren’t bad arguments, and they come from experience, but here are my responses:

• Incompetence on the part of someone else is not a good enough reason for me to do extra busywork that doesn’t add value.  If a dev is incompetent but willing to learn, comments aren’t the place to teach.  If they are incompetent and unwilling to learn, then they need to go.  If they can’t be removed, then the organization is likely destructive anyway, and no amount of comments is going to mean the difference between a successful project and a failed project.
• English is the language of programming, for better or worse.  And again, if the programmer is trying to improve their English skills, comments are not the place to learn spelling, grammar, etc.  If they’re unwilling to try to improve, see the first bullet point.

The main point of this chapter is: comments do not make up for bad code.  Clear code is better than comments.

However, sometimes comments make total sense.  A colleague of mine recently discovered that JavaScript’s month index is 0-based.  January = 0, February = 1, etc.  This is surprising behavior, and is a perfect place for a comment.

“The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that." (page 34)  When I was first learning programming, it was my understanding that functions should be used whenever you have a piece of code that you will reuse.  If you aren’t going to reuse it, it doesn’t need to be a function.  However, this overlooks an important feature of functions: their names.  Even if a function is only used once, even if doesn’t return anything, even if it doesn’t take parameters, it’s still useful to take a block of code and name it according to its intent.  Does this lead to a lot of functions?  Maybe.  So what?  It’s easier to read and maintain.

Functions shouldn’t have a lot of parameters.  A bunch of ‘out’ or ‘ref’ parameters is usually a clear sign that maybe another class should be created.  A function with one parameter is called a monad.  A function with two parameters is called a dyad.  A function with three parameters is called a triad.  A function with four or more parameters is called epic fail.

This chapter is a very good one, with lots of great guidelines for writing functions, and a lot of the stuff in this chapter can also be applied to objects & systems (as I’ve read in later chapters).

Phil Karlton famously said, “There are only two hard things in Computer Science: cache invalidation and naming things”.  If your code will ever be read by anybody (including yourself) anytime after it’s first written, naming is important.  A variable named “x” has no meaning in most contexts, and neither does “thingWhichDoesSomething”.  Chapter 2 lays down a lot of rules (of thumb) for naming variables, classes, methods, interfaces, etc.

One of the rules states that interfaces/implementations should not be named “ISomething” and “Something”, but rather “Something” and “SomethingImpl”.  This rule stood out from the other rules because it’s one that I disagree with.  I think this is mainly due to me being a .NET developer, where “ISomething” interfaces are common in the framework itself (IEnumerable, IList, etc).  Clean Code uses mainly Java examples, so this might be a convention that’s widely accepted outside of the Microsoft world.  Of course, in Ruby, Python, etc, this isn’t even an issue.  I totally understand Uncle Bob’s reasoning, and I’ve even seen the “Impl” naming used in .NET apps before, but I think I still prefer the “ISomething” naming.

A book that I read some time ago, Framework Design Guidelines, details many of the naming conventions and styles that the .NET framework developers used.  I found this a very entertaining read, and I think it provides a great baseline for .NET developers to work from, even if they aren’t writing frameworks/APIs all the time.  I think Chapter 2 is also a good baseline, but in the end, naming is about communication with other developers, and following a particular language/platform idioms is important to reducing confusion.

I purchased Clean Code by Robert “Uncle Bob” Martin, and I’ve been reading it as part of a) one of my goals set as part of my mentor program, and b) a book-club that I’ve co-started among a small group of developers in downtown Columbus.  As I am typing this, I’m currently at Chapter 8, but as a review and as a personal exercise, I thought I would go back and blog about one or two specific things, per chapter, that stood out as interesting or important.  Even though I’m not even halfway through, I think I could easily recommend this book to any developer who is passionate about coding, no matter their experience level.

Chapter 1 simply lays out the case for clean code: the whats, whys, and hows.  The most interesting part of this chapter is that Martin gets quotes from various prominent contemporaries about their personal definitions of “clean code”.  I won’t give them all to you, but I particularly liked this part of Michael Feather’s definition: “Clean code always looks like it was written by someone who cares”.  I don’t think any code is perfect, but clean code at least strives for perfection.  It’s not only expertise, but effort that can be seen in clean code.  That’s what I think when reading Feather’s definition, anyway.

The other interesting point that Martin makes is that There Will Be Code.  Which is to say, despite the efforts of model-driven development, domain-specific languages, etc, there will always be a need for programming and programmers.  The reasoning for this is pretty sound, I think: until there is some software that can detect intentions (not instructions), those intensions will have to be translated into formal instructions.  Technology will change,  software will change, computers will change, but someone will always need to be around to program them.  I don’t think he’s making a point about job security, but rather one about the necessity of craftsmanship, quality, and clean code: code is always going to be around, so let’s make it good code.