Use MAJOR Comments for Quick Scannability [DS1] [WHERE]
Tip DS1
The main goal of MAJOR comments is quick scannability - both for quickly finding a section of code and for forming a mental model of some code. Think about MAJOR comments like section headings in a book. Such comments can guide readers to the right section of code, and then they can start reading the relevant code.
While a general rule of thumb is to have a MAJOR comment for each major "step" in a block of code, that's a simplified rule of thumb that can work against the goal of MAJOR comments (quick scannability) if rigidly followed. If the goal of MAJOR comments is quick scannability, in order for that to be achieved, the MAJOR commenting structure should reflect the logical structure of code so that someone can easily jump to the different logical blocks.
This means there isn't necessarily a "one size fits all" policy for indicating if a given comment should be MAJOR or not. You need to look at the logical structure and context of a given piece of code, which could vary depending on what the code is doing.
The following examples show how MAJOR comments can be used to identify sections of code that a reader may need to easily jump to. They include some subtleties illustrating how there isn’t necessarily a “one size fits all” approach:
