Intersperse Comments with Individual Lines If That Eases Comprehension [DS21]
Tip DS21
In contrast to previous advice, if there are many low-level details that are important but not crucial to the overall understanding of a block of code, consider interspersing such comments before corresponding individual lines themselves. This is often useful for long lists of command line arguments, long function argument lists, or cases with multiple intermediate steps to set up some variables.
Placing all minor comments at the beginning of a block can sometimes make them too far from the corresponding code, particularly if there is a lot to comment on.
Below is an example for commenting individual command line arguments. The specific details of the command line arguments may not be that important to the larger surrounding block of code, but they are important for a maintenance programmer aiming to understand and debug the code:
