Keep MAJOR Comments to a Single Line [DS4]
Tip DS4
For MAJOR comments to be quickly scannable, they need to be reasonably short, which means fitting on one line.
If you find yourself writing a MAJOR comment that needs to span multiple lines, that is a warning sign that something is wrong - maybe the comment needs to be made more concise, maybe some content needs to go in minor comments instead, or maybe the code/commenting structure needs larger rework. Make adjustments as needed to keep MAJOR comments short enough to quickly read.
Not all intent can be captured concisely in MAJOR comments. The following example shows how it wasn’t possible to fully express the intent in a single-line MAJOR comment, so minor comments were used communicate additional details:
The following examples show multiple ways that MAJOR comments can both summarize and communicate intent:
