[h2s]

Never write comments that re-state the implementation.

    # Try to read the configuration file.

If this wasn't already obvious without the comment, then the code is a mess. Tidy the code up instead of painting over the problem with comments.

[aaronem]

That's a rule to be applied with a bit of nuance. Some things, especially in languages like Perl whose syntax already reads like a half-deliberate attempt to force an obscurantist style on the programmer, can't be made really obvious without doubling or tripling the length of the code in which they're implemented, something which imposes its own cost in readability and maintainability. In cases like that, it can be useful to add a few comment lines which briefly restate what the code implements, as both an aide-memoire for the original developer, and a minimal but immediately accessible answer to the question of "what the hell is this doing?" on the part of those who follow.

[robinh]

I agree wholeheartedly. The syntax doesn't even have to be extremely obscure, it can be highly useful in lower-level languages such as C as well: Often, I just want to get a quick idea of what the next big block of code is going to do without having to read the entire block of code.

[dougk16]

In that case it's often (yea I know, not always) better to put that block in a separate function, like readConfigurationFile() instead of "// This block reads the configuration file.". I almost always treat the act of writing comments as a signal that my code is a mess...although they're sort of a necessary evil when you're down to crunch time.

[henrik_w]

I agree, that's an excellent reason to create a function/method. Reason 7, self-documenting code: http://henrikwarne.com/2013/08/31/7-ways-more-methods-can-im... (but of course it doesn't mean that you never need comments)

[goblin89]

I think it's said that you should document the "why" (as opposed to "what"), which is relevant when you're using an unconventional approach or for some other reason your code may not be understood immediately, or when business logic is involved.

[robinh]

A fair point, I should probably have mentioned that. Thanks for pointing that out.

[derefr]

I would think that a comment re-summarizing the function in natural language would also "double or triple the length of the code." Wouldn't it be better, then, to just let the code itself expand, rather than expecting maintenance programmers to both read your comments, and then use them to parse an otherwise-inscrutable construction?

[aaronem]

> I would think that a comment re-summarizing the function in natural language would also "double or triple the length of the code."

It needn't; the example I had in mind when I wrote my earlier comment was some Perl code I wrote on Friday to automate the task of taking one database, full of relations dependent on auto-increment column values, and merge its contents into another database of identical schema but conflicting auto-increment values, while maintaining the relationships between rows. This worked out to ca. 60 lines of Perl, and unusually dense and hard-to-read lines even for that language; to this, I added about a half-dozen terse but informative comment lines to serve as guideposts for my primarily Python-hacking colleague and co-conspirator on this project.

A 10:1 code-to-comments ratio is unusually high, granted, and perhaps I could've instead written the code to use a lot more temporary variables and otherwise ballooned it out to twice or three times its length, but I don't see how that would've aided readability; on the one hand, there'd be a lot more state to keep track of, and on the other, it'd no longer fit on a single screen, and would thus require the reader to scroll hither and yon while trying to make sense of it.

Some things are inherently not simple, and I'd argue that complex manipulations of complex data structures fall well within that category -- in such cases, there's only so far you can simplify the algorithm before it ceases to work as you intend. When you write such code, you more or less have to rely on the native competence of whoever else has to work with it, because there's only so much hand-holding you can accomplish either in comments or in code.

Fortunately, in this case I can safely so rely; my colleague is at least as capable as I am, so the comments I added are the same sort I'd appreciate having when attempting to digest a complex algorithm in a language not wholly familiar to me -- for example, if he'd written this code in Python, rather than me writing it in Perl.

(Of course, the real problem is that, while both languages make it possible to perform the sort of manipulation necessary here, neither language is really well suited to it; if my colleague knew Lisp as well as I do, I could've written the bloody thing in fifteen elegant and highly readable lines, and we both could go on with our lives. But I've more or less given up hope of introducing Lisp at my place of work; even the most seasoned programmers among my colleagues, when exposed to parentheses, turn pale green and make excuses to be somewhere else in a hurry.)

[cema]

I think another exception (in addition to the already mentioned help with an otherwise difficult syntax) is when comments are used to visually represent logical segments of the code. Some style guides suggest to write these in all caps. Eg:

  # CONFIG
  ...
  # LOCALS
  ...
  # EDGE CASES
  ...
  # REFORMAT INPUT
  ...
  # MAIN ALGORITHM
  ...

Etc.

[h2s]

Rather than an exception, I think this is an example of the precise scenario in which it's most inappropriate to use comments.

    > visually represent logical segments of the code

This is exactly the use case in which function definitions excel. Use functions for this, not comments.

[akkartik]

Yeah. A past HN discussion caused me to realize that comments are often used for two independent purposes: structure and commentary. Conflating the two has caused many conversations with the participants talking past each other.

http://akkartik.name/post/2012-11-24-18-10-36-soc

[err4nt]

Maybe this is because I come from an HTML + CSS background, but if I'm adding code to a file that may need to be moved around within that file or transplanted to another file I often use comments to mark the start and finish of Sachs ection or 'block' of code.

It has little to do with how clean the code is, I can't imagine not having my way finding markers around!

[Hansi]

Agreed. I often try to make the point that when commenting people in my group should focus more on commenting on WHY and HOW rather than WHAT that is normally easily read from the code.

[streetnigga]

Such commentary goes at the top of a function or class. You get more nuanced as you delve deeper into the textual abyss.