• Comment your code - what it does, not how, unless it is not obvious from the code itself.
• Every phrase in the comments and documentation should start with a capital letter and end with a dot and 2 spaces. Rationale: GNU Coding Standards (the Emacs sentence commands will work).
• Documentation in javadoc/doc++ style: /** */, /// Example:

  /**
   * Search a string in a buffer.
   *
   * @param buffer the buffer in which to search.
   * @param string the string to look for.
   * @return the index of the first occurrence.
   */
  int findString(Buffer& buffer, String& string);
            

  Rationale: This allows the automatic generation of HTML documentation for the interface using doc++.
• Comment everything in headers. Rationale: This is where the interface is, and where people usually look for help.
• Leave two empty lines between functions in the *.cc files. Rationale: It makes it clearer where the body of a function starts/ends.
• Mark every bug and/or potential problem in the code with a comment starting with `FIXME: '. For instance: // FIXME: Parsing info not available. Rationale: This makes it very easy to locate such problems with tools like grep.
• Comment large amounts of code with:

  #if 0
  #endif
              

  Rationale: This avoids the comment inside comment errors at compile time if the code that you're commenting out contains other comments.

«Previous    1  2  3  4  5  6    Next»