What's wrong with comments that explain complex code?

In layman's terms:

• There's nothing wrong with the comments per se.
• What's wrong is writing code that needs that kind of comments.
• What's wrong is assuming it's OK to write convoluted code as long as you explain it friendly in plain english.
• Comments don't update themselves automatically when you change the code. That's why often times comments are not in sync with code.
• Comments don't make code easier to test.
• Apologizing is not bad. What you did that requires apologizing is bad.
• A programmer that is capable of writing simple code to solve a complex problem is better than one that writes complex code and then writes a long comment explaining what his code does.

Bottom line:

Explaining yourself is good, not needing to do so is better.

There's a bunch of different reasons for code to be complicated or confusing. The most common reasons are best addressed by refactoring the code to make it less confusing, not by adding comments of any kind.

However, there are cases where a well-chosen comment is the best choice.

• If it is the algorithm itself that is complicated and confusing, not just its implementation—the kind that get written up in math journals and are ever after referred to as Mbogo's Algorithm—then you put a comment at the very beginning of the implementation, reading something like "This is Mbogo's Algorithm for refrobnicating widgets, originally described here: [URL of paper]. This implementation contains refinements by Alice and Carol [URL of another paper]." Don't try to go into any more detail than that; if someone needs more detail they probably need to read the entire paper.

• If you have taken something that can be written as one or two lines in some specialized notation and expanded it out into a big glob of imperative code, putting those one or two lines of specialized notation in a comment above the function is a good way to tell the reader what it's supposed to do. This is an exception to the "but what if the comment gets out of sync with the code" argument, because the specialized notation is probably much easier to find bugs in than the code. (It's the other way around if you wrote a specification in English instead.) A good example is here: https://mxr.mozilla.org/mozilla-central/source/layout/style/nsCSSScanner.cpp#994 ...

  /**
   * Scan a unicode-range token.  These match the regular expression
   *
   *     u\+[0-9a-f?]{1,6}(-[0-9a-f]{1,6})?
   *
   * However, some such tokens are "invalid".  There are three valid forms:
   *
   *     u+[0-9a-f]{x}              1 <= x <= 6
   *     u+[0-9a-f]{x}\?{y}         1 <= x+y <= 6
   *     u+[0-9a-f]{x}-[0-9a-f]{y}  1 <= x <= 6, 1 <= y <= 6
  

• If the code is straightforward overall, but contains one or two things that look excessively convoluted, unnecessary, or just plain wrong, but have to be that way because of reasons, then you put a comment immediately above the suspicious-looking bit, in which you state the reasons. Here's a simple example, where the only thing that needs explaining is why a constant has a certain value.

  /* s1*s2 <= SIZE_MAX if s1 < K and s2 < K, where K = sqrt(SIZE_MAX+1) */
  const size_t MUL_NO_OVERFLOW = ((size_t)1) << (sizeof(size_t) * 4);
  if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
      nmemb > 0 && SIZE_MAX / nmemb < size)
    abort();
  

So what's wrong with explaining complicated code with a comment?

It's not a question of right or wrong, but of the 'best practice':

From http://en.wikipedia.org/wiki/Best_practice

A best practice is a method or technique that has consistently shown results superior to those achieved with other means, and that is used as a benchmark.

So the best practice is to try to improve the code first, and to use English if that is not possible.

It's not a law, but it's much more common to find commented code that requires refactoring than refactored code that requires comments, the best practice reflects this.

A day will come when your beautiful, perfectly crafted, well structured and readable code won't work. Or it won't work well enough. Or a special case will arise where it doesn't work and needs adjusting.

At that point, you will need to do something that changes things so it works correctly. Particularly in the case where there are performance problems, but also often in scenarios where one of the libraries, APIs, web services, gems or operating systems you are working with doesn't behave as expected, you can end up making suggestions that are not necessarily inelegant, but are counter-intuitive or non-obvious.

If you don't have some comments to explain why you have chosen that approach there is a very good chance that someone in future ( and that someone may even be you ) will look at the code, see how it could be "fixed" to something more readable and elegant and inadvertently undo your fix, because it doesn't look like a fix.

If everyone always wrote perfect code then it would be obvious that code that looks imperfect is working around some tricky intervention from the real world, but that isn't how things work. Most programmers often write confusing or somewhat tangled code so when we encounter this it is a natural inclination to tidy it up. I swear my past self is an actual idiot whenever I read old code I have written.

So I don't think of comments as an apology for bad code, but maybe as an explanation for why you didn't do the obvious thing. Having // The standard approach doesn't work against the 64 bit version of the Frobosticate Library will allow future developers, including your future self, to pay attention to that part of the code and test against that library. Sure, you might put the comments in your source control commits too, but people will only look at those after something has gone wrong. They will read code comments as they change the code.

People who tell us that we should always be writing theoretically perfect code are not always people with a lot of experience of programming in real-world environments. Sometimes you need to write code that performs to a certain level, sometimes you need to interoperate with imperfect systems. That doesn't mean that you can't do this in elegant and well written ways, but non-obvious solutions need explanation.

When I am writing code for hobby projects that I know nobody else will ever read I still comment parts that I find confusing - for example, any 3D geometry involves maths which I'm not entirely at home with - because I know when I come back in six months I will have totally forgotten how to do this stuff. That's not an apology for bad code, that's an acknowledgement of a personal limitation. All I would do by leaving it uncommented is create more work for myself in future. I don't want my future self to have to relearn something unnecessarily if I can avoid it now. What possible value would that have?

I think you're reading a little bit too much in to what he's saying. There are two distinct parts to your complaint:

What's wrong with explaining (1) a complex algorithm or (2) a long and convoluted piece of code with a descriptive comment?

(1) is inevitable. I don't think that Martin would disagree with you. If you're writing something like the fast inverse square root, you're going to need some comments, even if it's just "evil floating point bit level hacking." Barring something simple like a DFS or binary search, it's unlikely that the person reading your code will have experience with that algorithm, and so I think there should be at least a mention in the comments about what it is.

Most code isn't (1), however. Rarely will you write a piece of software that's nothing but hand-rolled mutex implementations, obscure linear algebra operations with poor library support, and novel algorithms known only to your company's research group. Most code consists of library/framework/API calls, IO, boilerplate, and unit tests.

This is the kind of code that Martin is talking about. And he addresses your question with the quote from Kernighan and Plaugher at the top of the chapter:

Don’t comment bad code—rewrite it.

If you have long, convoluted sections in your code, you have failed to keep your code clean. The best solution to this problem isn't to write a paragraph-long comment at the top of the file to help future developers muddle through it; the best solution is to rewrite it.

And this is exactly what Martin says:

The proper use of comments is to compensate for our failure to express ourself in code...Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.

This is your (2). Martin agrees that long, convoluted code does need comments -- but he puts the blame for that code on the shoulders of the programmer who wrote it, not some nebulous idea that "we all know that's not enough." He argues that:

Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments. Rather than spend your time writing the comments that explain the mess you’ve made, spend it cleaning that mess.

Do you disagree?

instead of other developers (including yourself) having to read the entire algorithm line by line to figure out what it does, they can just read the friendly descriptive comment you wrote in plain English.

I would consider this a slight abuse of "comments". If the programmer wants to read something instead of the entire algorithm, then that's what function documentation is for. OK, so the function documentation might actually appear in comments in the source (perhaps for extraction by doc tools), but although syntactically it's a comment as far as your compiler is concerned, you should consider them separate things with separate purposes. I don't think "comments should be scarce" is necessarily intended to mean "documentation should be scarce" or even "copyright notices should be scarce"!

Comments in the function are for someone to read as well as the code. So if you have a few lines in your code that are difficult to understand, and you can't make them easy to understand, then a comment is useful for the reader to use as a placeholder for those lines. This could be very useful while the reader is just trying to get the general gist, but there are a couple of problems:

• Comments aren't necessarily true, whereas the code does what it does. So the reader is taking your word for it, and this is not ideal.
• The reader doesn't understand the code itself yet, so until they come back to it later they still aren't qualified to modify or re-use it. In which case what are they doing reading it?

There are exceptions, but most readers will need to understand the code itself. Comments should be written to assist that, not to replace it, which is why you're generally advised that comments should say "why you're doing it". A reader who knows the motivation for the next few lines of code has a better chance of seeing what they do and how.

But we all know that's not enough.

Really? Since when?

Well designed code with good names is more than enough in the vast majority of cases. The arguments against using comments are well known and documented (as you refer to).

But these are guidelines (like anything else). In the rare case (in my experience, a about once every 2 years) where things would be worse when refactored into smaller legible functions (due to performance or cohesion needs) then go ahead - put in some lengthy comment explaining what the thing is actually doing (and why you're violating best practices).

What's wrong with explaining a complex algorithm or a long and convoluted piece of code with a descriptive comment?

Nothing as such. Documenting your work is good practice.

That said, you have a false dichotomy here: writing clean code vs. writing documented code - the two are not in opposition.

What you should focus on is simplifying and abstracting complex code into simpler code, instead of thinking "complex code is fine as long as it is commented".

Ideally, your code should be simple and documented.

This way, instead of other developers (including yourself) having to read the entire algorithm line by line to figure out what it does, they can just read the friendly descriptive comment you wrote in plain English.

True. This is why all your public API algorithms should be explained in the documentation.

So after writing a complex piece of code written in a partly human-readable programming language, why not add a descriptive and concise comment explaining the operation of the code in friendly and understandable English?

Ideally, after writing a complex piece of code you should (not an exhaustive list):

• consider it a draft (i.e. plan to re-write it)
• formalize the algorithm entry points/interfaces/roles/etc (analize and optimize interface, formalize abstractions, document preconditions, postconditions and side effects and document error cases).
• write tests
• cleanup and refactor

None of these steps are trivial to do (i.e. each can take a few hours) and the rewards for doing them are not immediate. As such, these steps are (almost) always compromized on (by developers cutting corners, managers cutting corners, deadlines, market constraints/other real world conditions, lack of experience etc).

[...] some algorithms are complex. And therefore are hard to understand when reading them line by line.

You should never have to rely on reading the implementation to figure out what an API does. When you do that, you are implementing client code based on the implementation (instead of the interface) and that means your module coupling is already shot to hell, you are potentially introducing undocumented dependendencies with every new line of code that you write, and are already adding technical debt.

Is it really that bad to explain a complex algorithm with a few lines of comments about it's general operation?

No - that is good. Adding a few lines of comments is not enough though.

What's wrong with explaining complicated code with a comment?

The fact that you shouldn't have complicated code, if that can be avoided.

To avoid complicated code, formalize your interfaces, spend ~ 8 times more on API design than you spend on the implementation (Stepanov suggested spending at least 10x on the interface, compared with the implementation), and go into developing a project with the knowledge that you are creating a project, not just writing some algorithm.

A project involves API documentation, functional documentation, code/quality measurements, project management and so on. None of these processes are one-off, fast steps to make (they all take time, require forethought and planning, and they all require that you come back to them periodically and revise/complete them with details).

The principal purpose of code is commanding a computer to do something, so a good comment is never a substitute for good code because comments can't be executed.

That being said, comments in the source are one form of documentation for other programmers (including yourself). If the comments are about more abstract issues than what the code is doing at every step, you're doing better than average. That level of abstraction varies with the tool you're using. Comments accompanying assembly language routines generally have a lower level of "abstraction" than, for example, this APL A←0⋄A⊣{2⊤⍵:1+3×⍵⋄⍵÷2}⍣{⍺=A+←1}⎕. I think that would probably merit a comment about the problem it's intended to solve, hmmm?

Is it really that bad to explain a complex algorithm with a few lines of comments about it's general operation? What's wrong with explaining complicated code with a comment?

The most useful description of good comments I ever heard is “a good comment is a true assertion” which means, a true assertion highlighting an important invariant of a program.

So for instance, when defining the tail recursive version of the factorial function in OCaml, we may explain code with a comment:

let fact n =
  let rec loop a k =
    (* fact n = a * k! *)
    if k > 0 then loop (a*k) (k-1) else 1
  in
  loop 1 n

A typical case where comments are misused, is explaining why rules of allocation and deallocation of resources — or some details of more complicated protocols — are satisfied by a program. It is much better to enforce these rules by using appropriate design patterns. For instance, the following OCaml code shows how to read from a file, ensuring that the file handler is closed even if some error occurs:

let with_file f filename =
  let c = open_in filename in
  try let answer = f c in (close_in c; answer)
  with exn -> (close_in c; raise exn)

By writing functions reading from a file as clients of with_file, we ensure that each opened file is closed, even if an exception is thrown, so that we do not write code leaking file descriptors. There is therefore no need to write comments explaining why file descriptors do not leak, except maybe in the description of the with_file function.

If the code is trivial, it doesn't need an explanatory comment. If the code is non-trivial, the explanatory comment will most likely also be non-trivial.

Now, the trouble with non-trivial natural language is that many of us are not very good at reading it or writing it. I'm sure your written communication skills are excellent, but nevertheless someone with a lesser grasp of written language might misunderstand your words.

If you try very hard to write natural language that cannot be misinterpreted you end up with something like a legal document (and as we all know those are more verbose and difficult to understand than code).

Code should be the most concise description of your logic, and there shouldn't be much debate about the meaning of your code because your compiler and platform have the final say.

Personally I wouldn't say that you should never write a comment. Only that you should consider why your code needs a comment, and how you might fix that. This seems to be a common theme in answers here.

I don't believe there's anything wrong with comments in code. The idea that comments are somehow bad in my opinion is due to some programmers taking things too far. There's a lot of bandwagoning in this industry, particularly towards extreme views. Somewhere along the way commented code became equivalent to bad code and I'm not sure why.

Comments do have problems - you need to keep them updated as you update the code they refer to, which happens far too infrequently. A wiki or something is a more appropriate resource for thorough documentation about your code. Your code should be readable without requiring comments. Version control or revision notes should be where you describe code changes you made.

None of the above invalidates the use of comments, however. We don't live in an ideal world so when any of the above fail for whatever reason, I'd rather have some comments to fall back.

Often we have to do complicated things. It's certainly right to document them for future understanding. Sometimes the right place for this documentation is in the code, where the documentation can be kept up to date with the code. But it's definitely worth considering separate documentation. This can also be easier to present to other people, include diagrams, colour pictures, and so on. Then the comment is just:

// This code implements the algorithm described in requirements document 239.

or even just

void doPRD239Algorithm() { ...

Certainly people are happy with functions named MatchStringKnuthMorrisPratt or encryptAES or partitionBSP. More obscure names are worth explaining in a comment. You could also add bibliographic data and a link to a paper that you've implemented an algorithm from.

If an algorithm is complex and novel and not obvious, it's definitely worth a document, even if only for internal company circulation. Check the document into source control if you're worried about it getting lost.

There is another category of code which isn't so much algorithmic as bureaucratic. You need to set up parameters for another system, or interoperate with someone else's bugs:

/* Configure the beam controller and turn on the laser.
The sequence is timing-critical and this code must run with interrupts disabled.
Note that the constant 0xef45ab87 differs from the vendor documentation; the vendor
is wrong in this case.
Some of these operations write the same value multiple times. Do not attempt
to optimise this code by removing seemingly redundant operations.
*/

I forget where I read it but there is a sharp and clear line between what should appear in your code and what should appear as a comment.

I believe you should comment your intent, not your algorithm. I.e. comment what you meant to do, not on what you do.

For example:

// The getter.
public <V> V get(final K key, Class<V> type) {
  // Has it run yet?
  Future<Object> f = multitons.get(key);
  if (f == null) {
    // No! Make the task that runs it.
    FutureTask<Object> ft = new FutureTask<Object>(
            new Callable() {

              public Object call() throws Exception {
                // Only do the create when called to do so.
                return key.create();
              }

            });
    // Only put if not there.
    f = multitons.putIfAbsent(key, ft);
    if (f == null) {
      // We replaced null so we successfully put. We were first!
      f = ft;
      // Initiate the task.
      ft.run();
    }
  }
  try {
    /**
     * If code gets here and hangs due to f.status = 0 (FutureTask.NEW)
     * then you are trying to get from your Multiton in your creator.
     *
     * Cannot check for that without unnecessarily complex code.
     *
     * Perhaps could use get with timeout.
     */
    // Cast here to force the right type.
    return (V) f.get();
  } catch (Exception ex) {
    // Hide exceptions without discarding them.
    throw Throwables.asRuntimeException(ex);
  }
}

Here there is no attempt to state what each step performs, all it states is what it is supposed to do.

PS: I found the source I was referring to - Coding Horror: Code Tells You How, Comments Tell You Why

One point not yet mentioned is that sometimes commenting precisely what a piece of code does can be helpful in cases where a language uses a particular syntax for multiple purposes. For example, assuming all variables are of type float, consider:

f1 = (float)(f2+f3); // Force result to be rounded to single precision
f4 = f1-f2;

The effect of explicitly casting a float to float is to force the result to be rounded to single precision; the comment could thus be viewed as simply saying what the code does. On the other hand, compare that code to:

thing.someFloatProperty = (float)(f2*0.1); // Divide by ten

Here, the purpose of the cast is to prevent the compiler from squawking at the most efficient way of accurately computing (f2/10) [it's more accurate than multiply by 0.1f, and on most machines it's faster than dividing by 10.0f].

Without the comment, someone who was reviewing the former code might think the cast was added in a mistaken belief that it would be needed to prevent the compiler from squawking and that it wasn't needed. In fact, the cast serves the purpose of doing exactly what the language spec says it does: force the result of the computation to be rounded to single-precision even on machines where the rounding would be more expensive than keeping the result in higher precision. Given that a cast to float can have a number of different meanings and purposes, having a comment specify which meaning is intended in a particular scenario can help make clear that the actual meaning lines up with intent.