Re:Notes on Programming in C (1989)
by redshirtrob on Wednesday October 04, 2017 @01:28PM
(#15402211)
I've been burned by bad comments enough times that I implicitly don't trust them. I wish this weren't the case but I think it's just human psychology. I'd rather unravel a mystery myself than deal with an unreliable narrator.
IDK, if you have self-documenting names, that sort of implies that they're close to unique/disambiguated. Which means that grep does a great job tracking down use (and declaration). And grep doesn't lie like out of date comments will.
I generally comment when I'm doing something really goofy because the 'obvious' method has some subtle flaw. A documentation for the next guy (who has a chance of being me, having forgotten some of the context six months form now) as a "I know you want to refactor this, but it's more complex than you think" warning.
This goes to "comments shouldn't describe the code, they should describe the reasoning". Especially if there are external reasons why the code is structured that way. On straightforward programs you should need hardly any comments at all.
I both agree and disagree with this... C is a small language, and it shouldn't take a huge amount of time to parse the source code to find out what's going on if variables / function names are self-documenting etc.
However, if you're dealing with a large code base and trying to track down where a variable is declared (and subsequently defined) for the purposes of maintenance or updating legacy code, comments hinting the what the structure underneath that label represents are incredibly useful (and more importantly, time and energy saving)