Notes About 97 Things Every Programmer Should Know

Some months ago, during my feedback session, I agreed to read 97 Things Every Programmer Should Know1 and do short presentations to the team about the articles that I've found interesting2.

In this post–and maybe in future ones–I'll share some of the notes I've taken about the book.

Comment Only What The Code Cannot Say

Original article by Kevlin Henney, here.

[…] to reduce the risk of overlooking any comments of genuine value, comments should be treated as if they were code. Each comment should add some value for the reader, otherwise it is waste that should be removed or rewritten.

There are lots of articles about how Comments Are Evil™ but this one doesn't (just) demonize them, it defines the only situation where they may exist:

Any shortfall between what you can express in code and what you would like to express in total becomes a plausible candidate for a useful comment. Comment what the code cannot say, not simply what it does not say.

What I gather from the article is that I should try to be as expressive as possible with the code before considering adding a comment.

Don't Be Afraid to Break Things

Original article by Mike Lewis, here.

I really like this article. What it wants to tell us is:

Don't be afraid of your code.

And I'll stop the quote there, otherwise I'll end up quoting the whole thing.

The take away is that, if we let the fear of breaking things slip into the project, then the technical debt will pile up since we won't be able to change, improve, remove, refactor, code that needs intervention.

We have tests in place, we shouldn't be worried about renaming a method, or changing how a service works even if that may break code out of the scope of the feature we're working at a specific moment.

The Boy Scout Rule

Original article by Uncle Bob, here.

The Boy Scouts have a rule: "Always leave the campground cleaner than you found it." If you find a mess on the ground, you clean it up regardless of who might have made the mess.

This article is very straight forward.

Indeed the act of leaving a mess in the code should be as socially unacceptable as littering. It should be something that just isn't done.

We should care for the team's code. It reminds me of XP's collective ownership of the code. It also reminds me of Martin Fowler's post on opportunistic refactoring.

  1. You can read the articles here and find more info about the book itself here 

  2. Interesting, beautiful, surprising, contradicting… 

Share this:

4 Replies to “Notes About 97 Things Every Programmer Should Know”

  1. Interesting Reading!

    Could you explain some examples of things that the code cannot express by itself so that it requires the help of (evil) comments?

    • Thanks Iván! And sorry for the late response.

      Your comment got me looking at real examples in our own codebase. There’s interesting stuff and more to write about it than I initially thought. I hope I can answer you in a more structured way (a new post, maybe) soon. 🙂

      But to reply with something. There are typical comments in configuration files where the DSL in use may not be enough to express the business rules behind. There a comment works better. Other places where comments seem necessary are in the system boundaries with the OS or with 3rd party libraries, where sometimes the exposed API or our app’s domain language are not enough to express why we are doing something, e.g. why do we coerce this field in the payload, why do we use the module Y instead of the built-in X?, why can’t we do this simpler?.

      These comments may indicate that the domain language should grow to cover these cases, but I guess you have to draw a line somewhere: there’s a cost and debt in writing these comments, but also in creating the infrastructure to make them superfluous.

    • Code is computational discourse: it answers questions like what and how. When those are not enough to understand why, I (should) add a comment.

Leave a Reply to Andrea Cancel reply

Your email address will not be published. Required fields are marked *