Like reading one chapter of a novel

A friend of mine shared an excellent analogy about commenting code the other day. He referred to code without comments like reading one chapter of a novel and expecting to understand the whole story. It really doesn’t matter how well the chapter is written, there’s just more surrounding information which makes it make sense.

This stemmed from a conversation regarding commenting philosophy in code. I’ve recently heard a couple times that code comments are a weakness and represent a failure to write the code in a transparent manner. That’s like saying that the last chapter of The Great Gatsby is a failure because you can’t understand the whole story by reading just that chapter.

Code does not exist completely stand alone. It must interact with other parts of the system, and depending on the design may or may not do certain things. To understand what a function does may require understanding what the child functions do and don’t do and how the entire transaction hangs together. Particularly, when we have to call external services, it’s helpful to have context. Code comments are like the Cliff’s notes or margin notes in a book. They help you quickly tie back to other parts of the code and understand why the code is doing something, not necessarily what it is doing,

I wholeheartedly agree that writing “//increment i” just before the line “i++” is a useless comment, but there clearly are uses for comments. Comments are not just those things used by “weak” programmers who can’t write code clearly enough. They serve a valuable purpose, particularly in understanding the intent of the code during code reviews.