What are the things Martin says about comments that you agree with?

I broadly agree with most of what Martin says in this chapter about “bad” and “good” comments. I think the taxonomy he provides is a reasonable one, although it might be missing a few things. Noise comments, redundant comments, journal comments, etc. are all just wasted space. I also think that what Martin says about expressing yourself in the code is broadly true.

I think the most important thing that Martin says that I agree with is that “comments lie”. In my experience this is so very often true. Some comments will be written once and then are not maintained. Over time, they can become less and less accurate, and that can be dangerous. It’s important to maintain code comments along with the code itself.

However, I think it’s reasonable to make a counterpoint here that “comments lie” can essentially be applied to everything in a codebase. It’s not uncommon for a developer to add something to a function in a way that makes the function’s name inaccurate. It’s not uncommon for a class to have its responsibility tweaked in a way that renders its name confusingly wrong. An example I’ve seen recently is that a given dialog, let’s call it SearchResultDialog, was recycled for another use case where the code was fundamentally the same but it had nothing to do with searches. The new code could have been called something like HomeScreenResultDialog. So what’s a Result in this case?⁴

So while I think anything can lie, the underlying message here is pretty clear. Comments have a maintenance burden, and if not maintained, will create problems for developers.

“Inaccurate comments are far worse than no comments at all”.

What are the things Martin says about comments that you disagree with (even situationally)?

I think I disagree with Martin’s assertion that:

“The proper use of comments is to compensate for our failure to express ourselves in code… Comments are always failures.”

Surely Martin can’t mean that, there are so many -

“Note that I use the word failure. I meant it.”

Oh. Well, then I fundamentally disagree. Documenting your public API with well-written JavaDoc is not a failure. Using comments to explain what a regular expression does so that some poor maintainer doesn’t have to decode it isn’t a failure. It’s good practice and professionalism.

“Only the code can truly tell you what it does.”

The code can only tell you what it does. It is much harder for code to tell you what it is meant to do. Comments can be wrong, they can lie, and so on; I freely acknowledge this indisputable fact. But Martin’s comments at the start of this chapter push developers to view comments as a foe, something to be eliminated at all costs. I argue that comments, JavaDoc, annotations etc. all serve a purpose. A professional developer should aim to understand where and when to use them appropriately.

To be honest, I think Martin doesn’t mean it, despite his protests. The chapter on the whole makes very good points about what good and bad comments look like. If Martin genuinely believed that all comments were failures, then there wouldn’t be a section in this chapter called “Good Comments”.

“There is nothing quite so helpful and satisfying as a well-described public API.”

What are the things Martin says that you think you do poorly?

At this stage in my career, I think I am broadly in alignment with the advice that Martin presents in this chapter. Unfortunately, I am very guilty of some of these sins previously in my career.

The use of Position Markers, comments that indicate “boundaries” in the code, is easily my greatest sin. I was even asked to stop at one point by a senior developer and kept doing it anyway. My reasoning at the time was that these aren’t arbitrary markers in the document. They’re visual indicators of how the code is split up, so that you can “home in” on specific sections of the code. Over time I found them to be less and less useful or important, and now I’m at a point where I cringe and quickly delete them if I come across any in my old code.

Despite this, I still think that some very large class files benefit, especially if it’s a large class that implements 2 complex and seemingly independent interfaces. It can be useful to segment the class file to clarify which methods are from which interface. Of course, this should be a red flag in itself that refactoring is needed!

Regarding HTML in comments, this is something that I try to avoid, but it’s unfortunately needed in some cases when writing JavaDoc. I would strongly prefer that we use something like Markdown instead as that is intended to be human-readable. Ultimately, JavaDoc is not meant to be consumed in its ‘raw’ form. So saying that HTML in JavaDoc is wrong, is a bit like saying you shouldn’t eat raw chicken with a spoon. You gotta cook that thing first!

Martin also decries JavaDoc in non-public code. I don’t really know what he means by “public”. If any other developer wants to use code I’ve written without having to understand it internally I’d want to provide a documented API to them (within reason). JavaDoc is just a documentation tool. The agile manifesto (of which Robert C. Martin was an original signatory) states “Individuals and interactions over processes and tools”. JavaDoc is a tool. Therefore it’s up to us, as the developers “trusted to get the job done”, to decide what should and shouldn’t be documented. I don’t think there’s anything wrong with adding JavaDoc to ‘internally-public’ code. That said I probably do miss the mark sometimes and document more than I need to.

One mistake I used to make that isn’t really covered in this chapter is the appropriate use of JavaDoc summaries. I would often write JavaDoc that looks like:

/**
 * @return X value of origin
 */
public int getX() {
    return x;
}

This is incorrect. JavaDoc expects a first line, ending with a full-stop, to be a “summary” that will appear next to the method in the class’ method listing. To avoid replication, this is preferred over any annotation tags. Therefore the above should be written as shown below.

/**
 * Returns the X value of the origin.
 */
public int getX() {
    return x;
}

What are the things Martin says that you think you do well?

I think I am generally quite good at writing documentation, meaning writing appropriate JavaDoc and capturing the intent of code. I think I am quite good at spotting something that might be confusing to future maintainers and clarifying it appropriately. Last year I received an ‘acknowledgement’ from another developer maintaining some code I had written many years before.

Working with a legacy codebase has its challenges, but it is almost always obvious when we are looking at a component written by David due to how incredibly well it is documented. This includes javadoc in the code, commit messages, and supplementary documentation on the wiki… Not only does the documentation explain HOW the code works (which is very welcome on its own), but also explains WHY we are doing things the way we are and why we are not doing it another way… This has saved us a great deal of time both when debugging the issue, and when coming up with alternative solutions.

While I am guilty of many sins with comments in the past, I think I am quite comfortable about my stance regarding the role of comments and code documentation in professional development. I try to live up to those standards as best I can.