MAJOR comments are one of the key techniques in helping readers navigate code. Understanding the following is important for effectively leveraging MAJOR comments:

Defining a “Block” of Code

Throughout these tips, MAJOR comments will be described in terms of “blocks” of code. The “term” block as used here is very loosely defined - it doesn’t necessarily map to a specific technical term as might be used when thinking formally about programming languages.

A “block” as used here can be thought of as any cohesive or connected sequence of one or more lines of code that can be grouped together (and often separated by blank lines), similar to a “paragraph.” That may often correspond to technical “blocks” of code defined by indentation or curly braces in programming languages, but it doesn’t have to.

For the purposes of MAJOR comments, the following can also be considered “blocks” of code:

1+ lines of straight-line code:

int build_exit_code = build.Run(workspace_folder_path);
return build_exit_code;

An if statement and the code in its body:

if (library_path_exists)
{
    command_line_arguments.push_back("/LIBPATH:" + library_path);
}

An if statement and code before it forming its condition:

std::size_t max_component_index = component_count - 1;
bool more_components_exist = (component_index < max_component_index);
if (more_components_exist)
{
    command << " ";
}

An if statement and closely-related code after it:

std::string current_component = Components[component_index];
std::size_t space_index_in_current_component = current_component.find(' ');
bool current_component_contains_spaces = (
    std::string::npos != space_index_in_current_component);
if (current_component_contains_spaces)
{
    current_component = "\"" + current_component + "\"";
}
command << current_component;

An if statement and its connected else statement:

if (all_projects_built_successfully)
{
    std::cout << "Build succeeded." << std::endl;
}
else
{
    std::cout << "Build failed." << std::endl;
}

A loop:

for (const Project* library : Libraries)
{
    library->AddIncludeFolderPaths(command_line_arguments);
}

The above isn’t an exhaustive list of everything that could be consider a “block” of code, but it should give you a good idea of what we mean when we refer to a “block” of code in relation to MAJOR comments.

Tips for Effective MAJOR Comments

See the following sections for more details on effective MAJOR commenting:

Effective MAJOR Commenting

Defining a “Block” of Code

Tips for Effective MAJOR Comments