Shift Comments to Minor to Better Support MAJOR Comment Quick Scannability If Needed [DS11] [WHERE]

When we covered effective MAJOR commenting, we mentioned that MAJOR comments were largely intended to support quick scannability and thus there wasn’t necessarily a one-size-fits-all approach to them.

An example was given of how multiple MAJOR comments were used to subdivide formation of some compiler options across multiple steps.

There were reasons given with that example for that decision. But what if considerations were different? What if the formation of those compiler options were part of a much longer function where the “compiler options” themselves were just a small part?

Factoring out such logic to a separate function is one way to solve this problem, which may be appropriate in many scenarios. However, sometimes there can be coupling between parts of the code such that the extra indirection and complexity that comes with a separate function isn’t worth it - having the code all in the same function is simpler. What can you do then to still support quick scannability via comments?

Well, you can subtly shift some comments from “MAJOR” to “minor.” When doing so, you typically want to shift the comments to communicate more intent or why, rather than just summarizing steps. The following shows how this can be done: