[hakunin]

Every once in a while I get an opportunity to share my 4 reasons to leave a code comment:

1. An odd business requirement (share the origin story)

2. It took research (summarize with links)

3. Multiple options were considered (justify decision)

4. Question in a code review (answer in a comment)

Important caveat for number 4: if your code can be restructured in a way that answers the question without a comment, do that instead.

This originally comes from an article[1] I wrote in 2021 titled "Writing Maintainable Code is a Communication Skill".

[1]: https://max.engineer/maintainable-code

[joshka]

I think there's probably a 5th one that's new-ish. Code isn't where the value is now that agentic tools can whip out a solution to just about anything in no time, so the commentary provides semantic grounding that allows you to navigate generated code easily.

It's kind of like some of the existing reasons, but there is a difference there.