3 ms·

Comments should explain why something was done not what it is doing. The code should explain what is being done and the comments give it context, so perhaps a l

Comments should explain why something was done not what it is doing. The code should explain what is being done and the comments give it context, so perhaps a legislation change meant rewriting something to do with tax or a bug caused by interacting with another piece of software required the change. That's what you comment not a human version of what the code is doing.

yotamkadishay 9y ago
But is it maintained like code? Maybe we can try to improve our code to avoid having many comments?
- Freak_NL 9y ago
  Good code is legible and may not have a lot of comments at all, but the comments that are there add value. And honestly, what codebase doesn't have these: // This looks weird and redundant, but is necessary because of a // sneaky bug in libbar (libbar issue tracker #123) that might be // fixed in their upcoming 2.0 release. Without it a race condition // can occur at seemingly random intervals. See our issue tracker // #456 for the whole nasty story. barProvider.fertilizeFoos(null); No amount of code is going to convey the same crucial information. And yes, a professional programmer will maintain that piece of documentation.