Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Common Comment Style

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...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment