This article argues against code comment supremacy and discusses the modern writing venues in software development.

The book "A Philosophy of Software Design" discusses code comments through three chapters. The author is enthusiastic about code comments and argues against Robert C. Martin's "comment as code smell" principle¹.

I used to be in Robert's camp, but after encountering many useful comments in real life, now I appreciate the values of good ones. Still, however, the enthusiasm in "A Philosophy of Software Design" puts me off. Such an extreme comment supremacy feels outdated: The author overlooks recent advances in software development tooling.

Today, software developers have various venues to leave written notes outside the code comments, for example:

• In-repo notes like a directory README.md
• Commit logs or PR messages
• Threads on issue trackers
• Other documentation tools like Wikis and Google Docs.

These have some advantages over traditional code comments:

• Better formatting capability: You can highlight words, have headlines, use tables or even put some images, thanks to Markdown or WYSIWIG.
• Conversational capability: Issue trackers and code review tools have a textbox. It allows you and your teammates to leave some extra comments, keeping the note a bit more nuanced and fresh.
• Stable URL: You can link the notes from almost anywhere, including the code comment.

On the other hand, the traditional code comment has only one strength: It lives next to the code itself, inline. This is nice and why it's been preferred.

Web-based Code Browser

However, the code comment's lead has eroded once Web-based code browsers like GitHub or Sourcegraph have become common. You can just put the URL to the note in the source code so that readers can click through. For a note to be accessible, it no longer has to stay inline.

Code browsers assist code (and note) reading. A few notable features are:

• It makes URL clickable: Although opening such a link can be cumbersome for text editors or IDEs, it's instant in Web-based code browsers. Links are the first class citizen on the Web.
• It makes blame handy: The commit log becomes a click away and the summary line even shows up next to the code itself. The code archeology has become a routine.
• It runs in the Web Browser: You have tabs. You have handy extensions. You can search the code, others' code, and StackOverflow, seamlessly.

In-Repo Notes

Among the new types of written notes, the in-repo notes are particularly powerful because:

• They live next to the source files.
• It is inherently versioned.
• It can be part of the code review.

In the other words, it is like the code, without suffering from the limitation of the code comment (lack of formatting, missing stable URL).

And like the code, you can refactor the notes, making the trade-offs: Inline comments are like inline code. They are handy and immersive. However, it can also be noisy and annoying, diluting the code density on the screen. Extract them into a separate in-repo note when that makes sense. It reduces the noise and increases the code density².

Also like code, don't repeat yourself. You don't have to explain a weird workaround. Leave a link to the relevant bug, that has a link to the relevant commit, that tells the story in detail. This is done only with a couple of clicks.

Suggestions

Let me rephrase the claim above as a few suggestions:

1. Read the code in the Web-based code browser, in addition to the text editor or the IDE. Treat the code browser as a read-optimized IDE. If you don't have one, invest.
2. Pick the right venue for your written note assuming the above is the norm.
3. Consider leaving links in the code to connect the relevant information.

In this world, you'll find the code comment less useful. That is not because the code is clean enough, but because the comment is no longer a primary place to leave the notes.

Looking from a different direction, Web-based code browsers turn code into hypertext. And the hypertext blurs the boundary between inside and outside the code. Take advantage of it.

This article doesn't discuss what should be noted in which writing venue, but it deserves a discussion. I might write about that at some point.

To Resonate

This article doesn't argue against the fundamental point the "Philosophies" book makes, that is, the importance of writing around the code. However, claims like this are convincing only when it is stated in relevant contexts for the readers. It doesn't resonate otherwise.

To be resonating and relatable, industry veterans like us have to re-tell the lesson in today's voice, instead of recommending old books. And the "Philosophies" book is a respectable attempt at that retelling. It delivers in some parts, but the comment sections are yet to reach that point in my opinion.

Footnotes

1. Robert later followed up on this topic.
2. Some IDE allows comment folding and it does help readability. If the code can tell the IDE to fold a specific part of the comment, it'll change the trade-off.