我的函数说明风格 

 1 /* 
 2  * 
 3  *        Judge whether a year is leap or common year.
 4  *
 5  * Param: 
 6  *        [Out]'leap': If 'year' is leap year, 'leap' will be 'true'; if common 
 7  *    year, 'leap' will be false. 
 8  *    otherwise, 'leap' is unchanged.
 9  *        [In]'year': The year you want to judge.
10  *
11  * Rtn: 
12  *        Always 0.
13  * 
14  * Note: 
15  *        How to decide a leap year? It should satisfiy the condition below:
16  *            1) 0 == year%4 && 0 != year%100
17  *            2) or 0 == year%400
18  *        'year' is the integer variable represent year.
19  * 
20  */
21 int w_isLeapYear(bool &leap, const size_t year);


关于空行:

  1. 前两行为空. 如第 1, 2 行. 
  2. 每一个分类之间有一个空行. 如第 4, 10, 13 都是不同分类之间的填充空行.
  3. 结尾两行为空. 如最后两行. 

关于缩进:

  1. 每个分类的标题与开头的 '*' 之间存在一个空格. 
  2. 分类标题后面紧接一个 ':' 和一个空格. 虽然这个空格是隐晦的. 准确的说, 除每行开头的 '*' 以及 '/*' 和 '*/' 之外, 每一个标点符号后面都应该有一个空格, 无论其是否可见.
  3. 正文与开头的 '*' 之间存在两个 Tab.
  4. 正文结束后紧接一个 '.' 和一个空格.

关于整体结构:

  1. 第一个分类是'概述'. 但是概述并没有分类的标题. 此分类是必选分类. 
  2. 第二个分类 Param, 即参数. 此分类是必选分类. 
    1. 每个参数正文格式如下: 
      　　　　[输入/输出/输入输出参数]'参数名': 参数说明. 
      　　　　[In/Out/IO]'variable name': explanation. 
    2. 无参则为 None. 
  3. 第三个分类是 Rtn, 即返回值. 此分类是必选分类. 在所有的 w_code 中, 凡是冠以 'w_' 前缀的函数皆为底层实现函数. 底层函数的返回值均为 int 类型. 0 代表正常执行, 其它值均为函数失败. 
  4. 第四个分类是 Note, 即附加说明. 此分类是可选分类. 通常记录函数的内部方法简述, 或为使用时的注意事项.
  5. 第五个分类是 Story, 即故事. 此分类是可选分类. 通常记录此函数的由来以及编写中所发生的故事. 这个分类的正文书写方式比较随意. 你可以写文字, 链接, 甚至画图等.
其他:
  1. 分类的标题, 首字母大写.
  2. 正文的首字母大写, 每句首字母大写(变量名除外). 
  3. 任何变量以 'variable' 方式引用.
  4. 任何一行文字不能超过 80 个字符(包括标点符号).

 

w_code 设计理念标准库相同: 即追求高效与安全1. 

注: 

  1. 为何高效在安全之前. 是因为当效率与安全无法共存时, 我们首先考虑效率. 这也是为什么至今有人使用 C++, 且 C++ 不会过时的原因.
posted @ 2012-02-19 16:23  walfud  阅读(176)  评论(0)  编辑  收藏  举报