[Boldewyn]

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), where they comment excessively, which browser quirk they address with which work-around.

[nmrm]

> 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]

> 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]

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)