- 不好的代码不应该试图通过注释解决,应该重写代码!
一般的,代码应该通过适当的名字选择与显式的逻辑结构做到自身文档化,应该少使用注释来弥补差的代码。
对编码层文档的主要贡献不是注释,而是好的程序风格。风格包含好的程序结构,直接使用和易于理解的方法、好的变量名、好的子程序名、命名常量、清晰的布局和最小的控制流及灵活的数据结构。
- 所有的注释应该用英文写。由于目前的用户主要是国内的用户,故建议使用中文。
- 源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的功能,主要函数及其功能、修改日志等。
- 对所有需要注释的使用//注释符,包括多行注释。
// Comment spanning
// more than one line.
既然C注释不支持多层,使用//注释确保当为了调试等原因时总能使用/* */在文件中注释一整块。
在“//“与实际注释间适用一个空白符,注释以大写字母开始以句号结束。
- 注释的位置应该与代码相关。注释的缩进应该和代码同步。
while (true) // NOT: while (true) {
{
// Do something // // Do something
something(); // something();
} // }
这样避免注释破坏了程序的逻辑结构。