5 ms·

I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code. One of th

I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code. One of the best cases for comments IMO is documenting an unexpected behaviour on the part of a third-party API. But even then, correct exception / error-handling code can obviate the need for comments in many cases. If I'm reading code (from an experienced programmer) and I see a comment, I immediately pay attention, because Here Be Dragons.

Boldewyn 12y ago
The situation must be differentiated by language/environment. The suggestions for Haskell are certainly not bad. They hold, too, for many systems programming. For scientific coding, comments should align with the underlying theory for the code: “This implements matrix transposition with regard to ... as defined by ...”, so that next generations can align code with papers better. And when you’re in a wacky environment like the PHP runtime or coding for a moving target like the browser, comments might be indispensable to explain one or the other really strange way of doing things, where you simply have no other choice. Look at the [jQuery source code](https://github.com/jquery/jquery/tree/master/src https://github.com/jquery/jquery/tree/master/src), where they comment excessively, which browser quirk they address with which work-around.
- nmrm 12y ago
  > For scientific coding, comments should align with the underlying theory for the code 100x this. Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain.
  - dragonwriter 12y ago
    > Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain. As someone who works as a programmer and system analyst dealing with code in a non-scientific business domain where I've also worked on the domain side, I don't think that this separates scientific code from any other codes. Programmers often disdain domain knowledge beyond that which they already have found to be immediately relevant. Which is perfectly understandable -- there's a reason they chose to specialize in programming rather than as domain experts in whatever domain.
    - nmrm 12y ago
      I thought through this some, and your comment resonates -- it's not right to set aside scientific code from other code with a complicated domain. But I think complicated program segments related to business practices etc. also deserves comments, even just "see spec xyz" or "see section 1.2.3 of code xyz" (similar to how you might say "See Smith et al. '14" in a scientific setting)
krfsm 12y ago
One case of unexpected behavior which is best described in comments is when the simple and obvious solution to the problem is wrong, and has already been discarded. (Preferably the reasons for discarding the simple solution should be provided as well, as circumstances may change.)
FranOntanaya 12y ago
I often have to go commando scripting small tasks to deliver things within the week, and the only comments I couldn't live without are TODOs to mark things that are hacked together. If time is limited I'd always rather write cleaner code than more commented code.
dscrd 12y ago
Remember your gas mask if you ever check out literate programming...

Boldewyn 12y ago

The situation must be differentiated by language/environment. The suggestions for Haskell are certainly not bad. They hold, too, for many systems programming. For scientific coding, comments should align with the underlying theory for the code: “This implements matrix transposition with regard to ... as defined by ...”, so that next generations can align code with papers better. And when you’re in a wacky environment like the PHP runtime or coding for a moving target like the browser, comments might be indispensable to explain one or the other really strange way of doing things, where you simply have no other choice. Look at the [jQuery source code](https://github.com/jquery/jquery/tree/master/src https://github.com/jquery/jquery/tree/master/src), where they comment excessively, which browser quirk they address with which work-around.

nmrm 12y ago
> For scientific coding, comments should align with the underlying theory for the code 100x this. Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain.
- dragonwriter 12y ago
  > Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain. As someone who works as a programmer and system analyst dealing with code in a non-scientific business domain where I've also worked on the domain side, I don't think that this separates scientific code from any other codes. Programmers often disdain domain knowledge beyond that which they already have found to be immediately relevant. Which is perfectly understandable -- there's a reason they chose to specialize in programming rather than as domain experts in whatever domain.
  - nmrm 12y ago
    I thought through this some, and your comment resonates -- it's not right to set aside scientific code from other code with a complicated domain. But I think complicated program segments related to business practices etc. also deserves comments, even just "see spec xyz" or "see section 1.2.3 of code xyz" (similar to how you might say "See Smith et al. '14" in a scientific setting)

krfsm 12y ago

One case of unexpected behavior which is best described in comments is when the simple and obvious solution to the problem is wrong, and has already been discarded. (Preferably the reasons for discarding the simple solution should be provided as well, as circumstances may change.)

FranOntanaya 12y ago

I often have to go commando scripting small tasks to deliver things within the week, and the only comments I couldn't live without are TODOs to mark things that are hacked together. If time is limited I'd always rather write cleaner code than more commented code.

dscrd 12y ago

Remember your gas mask if you ever check out literate programming...