The Essence Of A Useful Comment

When writing code, it’s always worth remembering that part of the purpose is that other people, and yourself 6 months later, will need to read it or understand it.

Comments in the code, and commit messages to source control are aspects of explaining this. The code itself should express clearly what it intends to do. Looking at the source file, function or class should give the intent.

The intent of comments should be the why. Why does this exist? It’s not so useful to say the name of the file, or the files in a commit. You can see that - it’s already clear. What is perhaps more interesting is to answer these questions “Why does this entity exist?”, “Why have I decided upon this design pattern/algorithm/style?”, “What trade-offs have I made here and why?”.