I originally wrote this list as a part of Writing Maintainable Code is a Communication Skill, then made a tweet. Since then, I had to link this list multiple times. This post makes it easier to link.
#Reasons
- An odd business requirement (share the origin story)
- It took research (summarize with links)
- Multiple options were considered (justify decision)
- 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.
