Focus Comments in the Problem Domain over Solution Domain [DL2] [WHAT]
Tip DL2
Code ultimately runs on a computer, but most code is designed to solve other real-world problems. Given that comments are intended to be at a higher level of abstraction that communicates more to readers than the code itself can, it’s very natural that many comments should be written in terms of the problem domain.
Writing comments in the problem domain offers several benefits. It helps connect the code to the real-world issues it addresses and educates fellow programmers about the problem domain, which helps them make sure their code is correctly handling the problem domain. Strive to comment as much in the problem domain as possible. If you don’t know or understand what the problem domain is, figure that out first - otherwise, your code might not actually solve the right problems!
A common way that solution domain, rather than problem domain, terminology can creep into comments is by referencing computer programming terms. For example, documenting that a file parameter is a file “object.” Leave off the unnecessary programming language concept of an “object” - it can complicate understanding, particularly if non-programmers try to the read the documentation.
Another way that solution domain terminology can creep into comments is by referencing exact code symbol names in comments. While documentation generator styles mean that you have to mention some code symbol names in comments, limit references to exact code symbol names to places needed to support documentation generators. When writing more prose comments, avoid referencing exact symbol names for the following reasons:
They less clearly refer to problem domain terms and may be harder for non-programmers to understand. Even if a symbol name might largely correspond to a problem domain term, prefer using official problem domain style/capitalization, rather than programmer-style naming conventions.
They can cause extra unnecessary maintenance burden to keep up-to-date. If the symbol name changes, someone has to remember to find and update the symbol name in all comments to keep the comments up-to-date (comments can’t be as strictly checked automatically like code). The underlying problem domain is more durable and thus less likely to change than a particular symbol name in code.
The following shows how programming language solution domain comments can be transformed into problem domain comments: