Examples In line Commenting Guide

Return to Example Process Flow

This document provides information for creating consistent inline comments for examples in the openFrameworks repository.

Considerations

Here are a few consistencies you can bring to every example in openFrameworks.

• Add a descriptive multi-line comment in the header file
• Add a top comment in the ofApp.h file.
• Should this explicitly say "ofApp.h"? Does this go above or below the #pragma once?
• Use a one line description of the example from the README.md
• Point to the README.md

    /*************************************************************************
    *
    * This Example demonstrates how to...
    *
    * For more information regarding this example take a look at the README.md
    *
    *************************************************************************/

General guidelines for in-line commenting

• Group related code together, separate by a space and add a line a comment above.
• Try to systematically add a one line comment for related blocks of code inside methods, especially the blocks of code showcasing the new methods introduced in the example.
• Avoid commenting obvious code.
• Comments should avoid direct reference to technical terms. Instead, state what the code below does in plain english.
• Add a space after your //.
• Break down long lines of code into multiple lines.
• Start your comments with a verb instead of a noun.
• Add separators between methods such as:

    //--------------------------------------------------------------``