注释规范

注释用途

  • 重复代码:使用不同词重申代码内容,毫无意义
      r = n/2;  //r是n的一半
      //循环,仅当r- n/r不大于t
      while ((r-n/r) <=t){
              r = 0.5 * (r-n/r); // 设置r变量
      }
 
  • 解释代码:解释复杂、有效灵敏的代码
    int a = 1;
    int b = 2;
    //交换a b的值
    a ^= b ^= a ^= b; 
 
  • 代码标记:表示工作未完成或开发者自身信息
    //TODO
    //EDIT BY WUQI 20140105
  
  • 概述代码:总结函数或代码块的作用
      //   DGETRS solves a system of linear equations
      //   A * X = B  or  A' * X = B with a general N-by-N matrix A using the LU 
      //   factorization computed by DGETRF. 
  
  • 代码意图说明:从问题上阐述代码的意义,例如:获取影像投影信息
    //DGETRF  computes  an  LU factorization of a general M-by-N matrix A 
    //  using partial pivoting with row interchanges.  
    //The factorization has the form A = P * L * U where P is the permutation matrix,
    //  L is lower triangular with unit diagonal elements
    //  (lower trapezoidal if m > n), and U is upper tri-angular 
    //  (upper trapezoidal if m < n) .
  

注释种类

  • 文件注释:.h文件头部写版权、版本、许可版本、作者,文件内容中写功能和用法的简单说明,cpp文件中写实现细节和算法讨论
    /**
      @file Matrix.h --文件名
      @brief 概述  
          详细概述  
      @author 作者,包含email等  
      @version 版本号(maj.min,主版本.分版本格式)  
      @history 修改历史,包括修改日期、修订原因和修订人信息
              2013.10.1    修改xxx    wuqi
              2013.10.5    修改xxxx    wupenghai
              ...
      @date 日期  
    */
 
  • 类注释:描述类的功能和用法的注释,必要时提供用法示例
  • 函数注释:说明参数、输入、输出、函数功能、实现要点、简要步骤;构造函数和析构函数非特殊情况不需要注释
  • 变量注释:通常变量名易懂即可,全局变量或有特殊取值范围等情况下做说明
  • 实现注释:复杂的代码块前;向函数传入bool或整数值时最好使用常量变量;隐晦的代码行尾写实现说明

注意事项

  1. c++中,使用$$或$/* */$,统一就好 - 注释要便于维护修改,而非整洁 - 使用伪代码注释先描述整个流程,然后实现伪代码逻辑,减少注释的时间 - 边编码边写注释,不要完成后再一起写 - 更新代码时更新注释 - 代码本身应该尽力做好说明 - 使用中文注释,不好翻译的专业词汇可用英文 ====== 编码规范 ====== * 尽可能给出描述性名称,不要节约空间,但不超过32个字符 * 除函数名可适当为动词外,其他命名尽量使用清晰易懂的名词 * 宏、枚举等使用全部大写+下划线 * 定义函数时,参数顺序为:输入参数在前,输出参数在后 * include时次序如下:C库、C++库、其他库的.h、项目内的.h * 函数体尽量短小、紧凑,功能单一 ====== 排版规范 ====== * 程序需要进行缩进 * vc6 Alt+F8 * VS2005及以上 Ctrl + K,Ctrl + F * Matlab Ctrl + I或鼠标右键,smart indent * 程序中统一使用空格或tab来缩进 * 有 $if$ $for$ 的地方一律需要括号括起来 * 整段有意义的代码也可以用括号括起来 * 每一行代码字符数不要太长,尽量不超过80 * 空行越少越好,循环、判断、函数等地方可以空行