Wow, telling people to comment their fucking code really hit a nerve. The reactions covered the whole spectrum from “just read Clean Code, dude” to “maybe some comments but just a little” to “OMG yes“.

Now that I cooled down, I’ll tackle the topic again with less furor. I planned to write about my perspective on high quality comments but last week’s discussions surfaced so many interesting view points and facts, that I wanted to cover those first.

Overview

What follows are some of your and my thoughts on comments. But this post can’t cover all there is to say about the topic. Please feel free to point out other factors you think are important!

Comments Versus …

… Documentation

Bitch please! You don’t know the fucking difference between comments and documentation and you rant about this!!

Moons

It turned out that we lack a shared understanding of whether API docs, like Javadoc or .NET’s XML documentation, are also comments. In the past week this sabotaged several interesting conversations and by now I must assume that it is a source of major misunderstandings in any discussion on the topic.

I am convinced that, yes, API docs are just comments, albeit specially formatted ones. This is backed by Wikipedia (see articles about comments or documentation generators), the documentation for Javadoc and .NET’s XML documentation, which both call them documentation comments, and the highest rated answers to related questions on StackOverflow and Programmers StackExchange.

Furthermore I consider all comments a form of documentation, even if it is just targeted at other developers, including future me. Of course, documentation can consist of more than just comments. Tests, example applications, diagrams, readmes, Wiki articles, and so forth can all be used to document a system.

But regardless of my interpretation of the terms it became obvious to me that any meaningful discussion about the topic must start with an exchange of what exactly we mean when we say comments.

When I say comments, all forms of documentation that lives in source files is included unless I specifically say otherwise.

… Clean Code

I will take code where the developers just don’t use variables all named “ufw”, “q”, “q1″, “ql”, “qi”, etc vs. over even full Javadoc (at the expense of other factors), any day.

Various_Pickles

I absolutely agree with Pickles. If it’s either clean code or value-adding comments, I prefer clean code as well. But why would it be either or?

This breaks down to a frequently voiced opinion: It is always better to invest time into cleaning code than into writing comments. Under the assumption that comments can add value (even if only rarely and only a little), this statement is clearly false. As the cost for improving code grows to infinity it must be at some point more effective to add comments.

This is especially true for comments which explain why a piece of code is written as it is. Clean code does little to provide such context.

In general I think that “good code without comments” versus “bad code with comments” is a false dichotomy. Clean code and good comments are complements in understanding a system. So why not spend time making the code as clean as possible and then add comments where they will help the future reader?

There is this prevalent notion in the software world that good code doesn’t need comments, that it stands on its own. Or that comments are a code smell. […]

Proponents of this myth point out that it’s easy for comments to get out of sync with the code and decide that because this approach is not perfect, it should be avoided altogether.

This is a false dichotomy that is easily avoided by making it clear to your teammates that both code and comments need to be reviewed.

Cedric Beust – Your code doesn’t speak for itself

Commenting Schema

In my rant as well as in this post, I have never gone out to say how I would like code to be commented. I am actually not sure yet but after talking about APIs I will make a very preliminary proposal.

APIs

As useful as javadocs are for public APIs, they are anathema to code that is not intended for public consumption.

Robert C. Martin – Clean Code

I consider the qualifier public ambiguous at best and misleading at worst. We should look for other characteristics to identify APIs worthy of documentation.

What Is Public?

Possible social interpretations are “the general public”, “everyone outside the company”, “everyone outside the department” and so on. More technical interpretations are “everyone calling this code from another system” and “everyone calling this code from another module”.

In the extreme case this allows developers to claim that since their code is not called by anyone outside the company, there is no need to write any comments.

More commonly, public is understood as “calls from outside the assembly” (e.g. from another JAR). But then it suddenly makes a difference whether some often used code is living inside another assembly or in its own. This doesn’t make much sense, either.

What Is Important?

APIs are the epitome of reusable code. A popular public API might be used by hundreds of thousands or even millions of developers. It gets popular by abstracting a substantive problem in an approachable way. A great enabler of this is a helpful documentation of which contract comments are an integral part.

Back to the puny little APIs we write, be they anti-corruption layers, sets of utility methods, handcrafted UI controls, or any other piece of code we hope will be used throughout our codebase. While most likely less successful, similar rules apply. They solve concrete problem domains and provide abstractions for others to use, which users will do more easily if they can find their way around.

So instead of gauging an API by how public it is, we should consider how it will penetrate our codebase. The more often it will be used, the better it should be documented.