3 ms·
Code commenting is an activity that's hard to get just right; it seems there's either not enough, or none at all or even worse - too much! I've found the follo
by taylodl 8y ago
Code commenting is an activity that's hard to get just right; it seems there's either not enough, or none at all or even worse - too much!
I've found the following works really well: when doing something non-obvious then comment it immediately. Otherwise wait to see what arises from the Amigo Review. If the reviewer asks any questions, answer them with comments. Once the reviewer stops asking questions then the code is sufficiently commented.
- BonesJustice 8y agoNot just when doing something non-obvious, but also when not doing something that might normally be expected. “We don’t need to synchronize here because <some invariant>” and whatnot. Basically, whenever a casual observer might think there’s a bug, either because you’re doing something unexpected or not doing something expected.
- splonk 8y agoI like this process, although I'm not as consistent as I'd like to be about answering in comments rather than in the review tool. As an addendum to this, I have a general rule for code review: the developer doesn't get to push back on any (correct) request for comment/renaming/clarification. I'm prepared to accept that the fact that somebody felt the need to ask something is proof enough that the code in question isn't as obvious as I thought.