[j-kidd]

In my opinion, the full explanation is too long to be put as code comment, but is just right as the commit message. The best way is to keep the commit message, but add a short comment like:

    // Hack to trigger layout change in latest Mozilla

Then, whoever interested in the hack can read the full explanation from the commit message.

Basically, for simple code with unclear purpose, I'd go with short comment in the code plus full explanation in the commit message. For hard-to-read code with complicated logic, I'd go with long comment in the code. Or refactoring.

Ticket description, commit message, code comment, and the code itself are all necessary to keep the codebase "documented".

[_delirium]

If the codebase is associated with a reasonably stable bug-tracker, I'd also put a bug # or a URL in the source comment if it's something nonobvious that is important for future maintainers to be aware of, but considered too long to document inline (if it's purely of historical interest, then yeah, leave it to the VCS history). Or a link to an archived mailing list discussion, or a CVE id, or some kind of hint.

[crazygringo]

I'm genuinely curious -- what is the thinking behind "too long to be put as code comment"? I've never heard that before.

It's not like we're conserving paper. And syntax highlighters helpfully give comments different colors so you can skip over them while reading.

Personally, I've never once wished that a particular piece of code were less commented, but there are hundreds if not thousands of times I've wished that there was more explanation, or any at all.

[salgernon]

Comments are frequently out of date with the code that they're describing. This tendency is somewhat linear with the length if a comment and therefore longer comments will be more incorrect, more quickly. I'm not being facetious, this is a readily observed phenomena.

[einhverfr]

Long comments get out of date quickly because it isn't clear how the comments relate to the code on a quick scan. In this case, you want a quick note as to why the code is there. You can add external references if needed.

You don't want to make someone who is editing code stop to think about how it affects the comments.

[tsiki]

>You don't want to make someone who is editing code stop to think about how it affects the comments.

What's the point of comments then if your general rule is that it should be fine to edit code without changing the comments?

[einhverfr]

> What's the point of comments then if your general rule is that it should be fine to edit code without changing the comments?

Not without changing the comments. Without stopping to ponder how two paragraphs of comments fit into the code changes. The comments (aside from API documentation) should annotate the code, not the other way around.