From ScorecWiki

Use Doxygen format for comments. For general information on Doxygen, see the SCOREC Research Wiki. Write comments clearly, in English, with proper grammar and punctuation.

Contents 1 File Header 1.1 API header file 1.2 All other files (.h, .cc, .c) 2 File Content 2.1 Namespace 2.2 Class 2.3 Function 2.4 Variable

File Header

Every source file should start with the SCOREC license.

/****************************************************************************** 

  (c) 20xx-2010 Scientific Computation Research Center, 
      Rensselaer Polytechnic Institute. All rights reserved.
  
  The LICENSE-SCOREC file included with this distribution describes the terms
  of the SCOREC Non-Commercial License this program is distributed under.
 
*******************************************************************************/

Note: Set the start year properly (contact project manager if not clear)

API header file

/** \mainpage Project Name e.g. Geometric Modeling Interface (GMI)
 * 
 * @file      file name (no relative path)
 * @date      July 1, 2010 (<-- our target date of first release)
 * @version   0.1
 *    <-- INSERT BLANK LINE -->
 * @brief     brief description
 *    <-- INSERT BLANK LINE -->
 *  @remark    extended description (reserve space)
 *    <-- INSERT BLANK LINE -->
 */

Example:

All other files (.h, .cc, .c)

/**
 * @brief     project name (e.g. FMDB, GMI)
 * @file      file name (relative path should be included e.g. /cint/FMDB.h)
 *    <-- INSERT BLANK LINE -->
 * @brief     brief description
 *    <-- INSERT BLANK LINE -->
 * @remark    extended description (reserve space)
 *    <-- INSERT BLANK LINE -->
 */

Example:

File Content

Do not duplicate comments between the .h and .cc files. The .h file should contain the below templates to detail how to interface with your code. The comments in the .h file should explain what classes and functions do, but not how they do it. From the Google standard: These comments should be descriptive ("Opens the file") rather than imperative ("Open the file"); the comment describes the function, it does not tell the function what to do.

The .cc file should contain comments that describe the details of implementation. That is, the comments in the .cc file should explain how the algorithms work. Do comment extensively here, but do not put comments that are trivial. When in doubt, include a comment that you think might be trivial. A good example from Google: Do not be unnecessarily verbose or state the completely obvious. Notice below that it is not necessary to say "returns false otherwise" because this is implied.

// Returns true if the table cannot hold any more entries.
bool IsTableFull();

Be smart about placing your comments so that they are visible, and it is obvious which portion of code they are describing. Some nice examples:

Lining up comments on different lines to describe the inputs to a function:

bool success = CalculateSomething(interesting_value,
                                  10,     // Default base value.
                                  false,  // Not the first time we're calling this.
                                  NULL);  // No callback.

Putting a comment before a chunk of complicated code

// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
  x = (x << 8) + (*result)[i];
  (*result)[i] = x >> 1;
  x &= 1;
}

Namespace

/**
 * @namespace namespace name
 * @brief     brief description
 * @remark    extended description (reserve space)
 */

Example:

<code class="c">
/**
 * @namespace SCOREC::Ocean
 * @brief     This namespace contains fundamental classes and
 *            interfaces that form the basis of Ocean framework.
 * @remark    Here we would write more detailed stuff about the 
 *            SCOREC::Ocean namespace.
 */
namespace SCOREC
{
  namespace Ocean
  {
  }
} // SCOREC::Ocean
</code>

Class

/**
 * @class     class name
 * @brief     brief description e.g. main functionality
 * @remark    extended description (reserve space)
 */

Example:

Function

/**
 * @brief     brief description
 * @remark    extended description (reserve space)
 *    <-- INSERT BLANK LINE -->
 * @param     parameter name  (In, Out, or InOut) description
 * @return
 */

Here (In) is used to denote that a particular parameter is used for input. If a parameter is used for output, use (Out). If a parameter is both input and output (that is, it has an initial value but it is modified by the function), use (InOut). In the .c / .cc files, comments are basically put to explain the portions of the code for better understanding. There could be also brief comments about the variables and functions which were not included in the .h files. Comments are not counted towards the maximum allowed function length.

Example:

/**
 * @brief     Defines whether the given entity is a BL entity.
 * @remark    Given an entity, the function returns 1 if the entity
 *            belongs to a BL, and 0 otherwise.
 * 
 * @param     ent  (In)  Entity.
 * @return    1 if entity is a part of BL, or 0 otherwise.
 */
int EN_isBLEntity(pEntity ent);

More good advice from Google: When commenting constructors and destructors, remember that the person reading your code knows what constructors and destructors are for, so comments that just say something like "destroys this object" are not useful. Document what constructors do with their arguments (for example, if they take ownership of pointers), and what cleanup the destructor does. If this is trivial, just skip the comment. It is quite common for destructors not to have a header comment.

Variable

If purpose of variable is not clear from its name, then a comment is required. Variables can be commented with "brief" comments (e.g., "/// Comment").

Example:

/// number of fish in the pond
int iNumFish;