Examples In line Commenting Guide

Jeff Gray edited this page Feb 21, 2016 · 5 revisions

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.

Also, please refer to the larger oF coding style guidelines and doxygen documentation guidelines. Consistency is good for everyone!

  • Add a top comment in the ofApp.h file.
  • Use a one line description of the example from the README.md
  • Point to the README.md
    // Refer to the README.md in the example's root folder for more information on usage. 

General guidelines for in-line commenting

  • Group related code together, separate by a space and add a line a comment above.
  • Use punctuation and full sentences.
  • 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:
    //--------------------------------------------------------------``