C++注释规范

Posted on | In , ,

良好的文档及注释对于程序开发理解有举足轻重的作用，它应当帮助人们理解如下问题1：

  • 类间继承关系
  • 全局变量
  • 不同的用户定义类型
  • 函数使用

本文将以文档生成工具doxygen为例，对C++的注释规范进行总结。

QT下自动注释生成

在类、函数或变量的前面写/**，然后回车，会自动生成doxygen风格的注释。

1
2
3
/**
 * @brief The lambertian class    
 */

基于doxygen的代码注释风格

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/∗! \file globaldecls.h
    \brief Place to look for global variables, enums, functions and macro definitions
∗/

/∗∗ \var const int fileSize
    \brief Default size of the file on disk
∗/
const int fileSize = 1048576;

/∗∗ \def SHIFT(value, length)
      \brief Left shift value by length in bits
  ∗/
#define SHIFT(value, length) ((value) << (length))

/∗∗ \fn bool check_for_io_errors(FILE∗ fp)
      \brief Checks if a file is corrupted or not
      \param fp Pointer to an already opened file
      \warning Not thread safe!
  ∗/
bool check_for_io_errors(FILE∗ fp);

reference

0%