> This is one of the most important skills to learn as a developer: when to add a comment explaining the reason for some non-obvious code — and also how to writ

> This is one of the most important skills to learn as a developer: when to add a comment explaining the reason for some non-obvious code — and also how to write it so that enough context is given for the future reader, who may not have the same understanding that you have of the rest of the codebase and the business requirements. I have the benefit of working on a team with impressively rigorous review habits, and the detriment of being comment-averse when I write code (because I’ve more often than not been bitten by comments that are plainly wrong but only in retrospect). So this probably doesn’t apply to most, but here’s my heuristic for when to add a code comment: did someone ask a question about it, or something which could be traced back to it? That’s it, the whole comment strategy. I answer questions people actually asked. At which point I generally provide a lot of detail, because if it’s worth asking, it’s worth answering in one place or at least providing a single frame of reference to jump off to other contextually pertinent details.