MAJOR and Minor Comments

“MAJOR” and “minor” comments are a useful way to think about different kinds of comments.

“MAJOR” comments tend to capture or summarize the most important, high-level, or “major” steps or sections in a given body of code. They are aimed at quick comprehension and navigation of blocks of code, identifying key parts of “what” code is doing. Ideally, a programmer should be able to leverage MAJOR comments to quickly scan through a block of code and find the relevant sections he/she needs to understand or change.

“Minor” comments tend to provide additional details that cannot be concisely communicated in MAJOR comments and aren’t part of the essential “what” of what code is doing. These often contain key details and explanations important for maintenance programmers but can typically be skipped for someone quickly skimming code to get a high-level overview of its structure/steps. It is relatively common for minor comments to exist directly after many MAJOR comments to provide additional explanations, but minor comments can also exist elsewhere not on lines directly after MAJOR comments.

This training leverages UPPERCASE or FULL CAPS for “MAJOR” comments because it provides a small, low-cost stylistic distinction that makes them stand out and easier to separate from other comments. “Minor” comments will use normal sentence capitalization.

See the following for more details on MAJOR and minor comments:

Below is an example of code leveraging both MAJOR and minor comments:

public void AbortMaintenance()
{
    // TRIGGER THE CANCELLATION TOKEN.
    // This will cause any asynchronous tasks that use the token to
    // bail out of execution.
    cancellationTokenSource.Cancel();

    // GET THE TASKS THAT ARE CURRENTLY RUNNING.
    Task[] tasksToWaitFor = new Task[]
    {
        fullReindexingTask, 
        mergeIndicesTask, 
        refreshMergedIndexTask
    };

    // WAIT FOR THE RUNNING TASKS TO BE FINISHED.
    // This is a blocking call that will not return until after all of the
    // tasks have returned from execution.
    // If a task is cancelled, then an exception will occur.
    try
    {
        Task.WaitAll(tasksToWaitFor);
    }
    catch (Exception)
    {
        // Do nothing.  An exception is expected when the tasks are cancelled.
    }

    // RESET THE CANCELLATION TOKEN.
    // The new cancellation token will be used for any new tasks that are started.
    cancellationTokenSource = new CancellationTokenSource();
}