2.1.5 Commenting Code

  • Comment your code when you do something that someone else may think is not trivial.

  • Comments for pure virtual functions, documentation for API usage should be placed in front of (member, or non-member) function declarations. Description of implementation details, algorithms, anything that does not impact usage, should be put in front of implementation. Please try to not duplicate information. Make a reference to the declaration from the implementation if necessary. If the implementation and usage are too interleaved, put a reference from the interface to the implementation, and keep the entire comment in a single place.

  • Class comments should be put in front of class declaration.

  • When writing multi-line comments please put the '/*' and '*/' on their own lines, put the '*/' below the '/*', put a line break and a two-space indent after the '/*', do not use additional asterisks on the left of the comment.

  This is how a multi-line comment in the middle of code
  should look.  Note it not Doxygen-style if it's not at the 
  beginning of a code enclosure (function or class).

 /* ********* This comment is bad. It's indented incorrectly, it has
 *            additional asterisks. Don't write this way.
 *  *********/
  • When writing single-line comments, the '/*' and '*/" are on the same line. For example:

 /* We must check if stack_size = Solaris 2.9 can return 0 here. */ 
  • Single-line comments like this are OK in C++

 // We must check if stack_size = Solaris 2.9 can return 0 here. 
  • For a short comment at the end of a line, you may use either /* ... */ or a // double slash. In C files or in header files used by C files, avoid // comments.

  • Align short side // or /* ... */ comments by 48 column (start the comment in column 49).

 { qc*= 2; /* double the estimation */ } 
  • When commenting members of a structure or a class, align comments by 48th column. If a comment doesn't fit into one line, move it to a separate line. Do not create multiline comments aligned by 48th column.

struct st_mysql_stmt
  MYSQL_ROWS     *data_cursor;         /**< current row in cached result */
  /* copy of mysql->affected_rows after statement execution */
  my_ulonglong   affected_rows;
  my_ulonglong   insert_id;            /**< copy of mysql->insert_id */
    mysql_stmt_fetch() calls this function to fetch one row (it's different
    for buffered, unbuffered and cursor fetch).
  int            (*read_row_func)(struct st_mysql_stmt *stmt,
  • All comments should be in English.

  • Each standalone comment must start with a Capital letter.

  • There is a '.' at the end of each statement in a comment paragraph (for the last one as well).

  This is a standalone comment. The comment is aligned to fit 79 
  characters per line. There is a dot at the end of each sentence.
  Including the last one.
  • Every structure, class, method or function should have a description unless it is very short and its purpose is obvious.

  • Use the below example as a template for function or method comments.

    • Please refer to the Doxygen Manual for additional information.

    • Note the IN and OUT parameters. IN is implicit, but can (but usually shouldn't) be specified with tag @param[in]. For OUT and INOUT parameters you should use tags @param[out] and @param[in,out] respectively.

    • Parameter specifications in @param section start with lowercase and are not terminated with a full stop/period.

    • Section headers are aligned at 2 spaces. This must be a sentence with a full stop/period at the end. Iff the sentence must express a subject that contains a full stop such that Doxygen would be fooled into stopping early, then use the @brief and @details to explicitly mark them.

    • Align @retval specifications at 4 spaces if they follow a @return description. Else, align at two spaces.

    • Separate sections with an empty line.

    • All function comments should be no longer than 79 characters per line.

    • Put two line breaks (one empty line) between a function comment and its description.

  Initialize SHA1Context.  

  Set initial values in preparation for computing a new SHA1 message digest.
  @param[in,out]  context  the context to reset
  @return Operation status
    @retval SHA_SUCCESS      OK
    @retval != SHA_SUCCESS   sha error Code
int sha1_reset(SHA1_CONTEXT *context)

User Comments
Sign Up Login You must be logged in to post a comment.