Where Lower-Level Technical Comments Are More Justified
While commenting in the problem domain as much as possible is ideal, because we are documenting code that may have all sorts of quirks to it, we can’t completely avoid lower-level technical comments. There are two main categories where lower-level technical comments are still appropriate:
Documenting important usage considerations for other programmers - When using a class, function, etc., there may be technical usage considerations that are important for other programmers to be aware of. It’s better to make sure these are documented rather than left out. These are discussed in more detail in the section on commenting code interfaces.
Documenting important maintenance notes for future programmers - Technical details such as performance considerations, bugs, and other maintenance-related issues can be crucial for future maintenance programmers. Documenting these details can help ensure successful maintenance and prevent mistakes. These are discussed in more detail in the section on commenting for maintenance programmers.
When writing comments like this, first make sure the relevant problem domain is clearly commented on first. Then dive into lower-level technical details as needed.
