Common Comment Style

gistfile1.md

Common Comment Style

Cause i didn't find a useful one, i try to define it for personal using. So some rules are strict.

These ideas come from javadoc and doxygen.

Common rule

• markdown for the format of internal comment
• do not comment everywhere, you are doing coding not commenting

Dispute

• @version can be saved into a stand alone file like VERSION if user forgets the version he downloaded in some distribution. Then if you get a release version, it is simple to find out the version of that file

File

/**
 * @file filename.ext
 * description...
 *
 * @author yarco <yarco.wang@gmail.com>
 * @since 2012/11/28
 * @copyright BSD
 */

Class

/**
 * @class classname
 * description...
 */

Variable

var v; //<! description...

Function/Method

• short version

//! short description

• long version (+ vim folding)

/** brief description {{{
 *
 * long description...
 *
 * @param type description...
 * @return type description...
 * @throws type description...
 * @see somewhere
 * @api public,deprecated
 */

/*}}}*/

Other

// TODO: description...