C/C++ 程序员编程规范之注释

编程规范(注释)

注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。

---

说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释.

     注释适当列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。

源文件头部也应进行注释.

     列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。

函数头部应进行注释

     列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。

边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

注释的内容要清楚、明了，含义准确，防止注释二义性。

    

避免在注释中使用缩写，特别是非常用缩写。

注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置.

   如放于上方则需与其上面的代码用空行隔开。

对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。

    变量、常量、宏的注释应放在其上方相邻位置或右方。

注释格式尽量统一，建议使用/* …… */

在代码的功能、意图层次上进行注释，提供有用、额外的信息。

在程序块的结束行右方加注释标记，以表明某程序块的结束。

对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释

对变量的定义和分支语句（条件分支、循环语句等）增加注释

将注释与其上面的代码用空行隔开,注释与所描述内容进行同样的缩排.

全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明.

数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。

 

其他

1. **文档生成工具**：如果你使用的编程语言或框架有相关的文档生成工具（如Java的Javadoc、Python的Docstrings、C++的Doxygen等），建议遵循相应的注释格式，以便自动生成API文档。
  

2. **代码示例**：对于复杂的函数或模块，可以在注释中给出一个简单的使用示例。
 

    def complex_function(param1, param2):
        """
        This function does something complex.
        
        Example:
        ```
        result = complex_function(1, 2)
        ```
        """
        pass

3. **引用和链接**：如果代码是基于某篇论文、算法描述或其他外部资源，建议在注释中给出相关的引用或链接。

4. **TODO 和 FIXME 标签**：在注释中使用 `TODO:` 标签来标记未完成的工作，或者使用 `FIXME:` 标签来标记需要修复的问题。
 

    // TODO: implement this function
    // FIXME: this part of code has a bug

5. **单位和约束**：如果变量或函数参数有单位（如时间、长度等），或者有某些约束（如取值范围、是否可以为null等），这些信息也应该在注释中明确。

6. **版本和修改历史**：除了文件头部，当某个函数或模块有重大更改时，也可以在其注释中添加版本或修改历史。

7. **注释的可读性**：注释也是代码的一部分，因此也要保证其可读性。避免使用过于复杂的句子或专业术语，确保即使不熟悉项目的人也能理解。

8. **国际化**：如果你的代码将被多国或多文化的开发者使用，考虑使用英语进行注释，或者提供多语言的注释选项。

9. **避免显而易见的注释**：如果代码本身就非常清晰和自注释，过多的注释反而会降低代码的可读性。

记住，好的代码应该是“自注释”的，即通过合理的命名和结构使代码尽量易于理解。然而，注释是为了解释代码不能清楚表达的所有信息，如设计思想、重要决策等。因此，注释和代码应该相互补充。