原则1: 关于函数注释 说明 关于使用(某函数)方法的注释： (头文件中)函数声明之前，要给出恰当的注释，从而让使用者无需了解实现细节就能够快速获得足够的信息来使用该函数：同时这些信息又是精炼的，没有不相关的内容。 关于(某函数)实现的注释： 在函数实现之前，要给出和实现有关的足够而精炼的注释信息。 例子 /***************************************************************** *函 数 名：XXXXXXXX *功 能：XXXXXXXXX *入口参数： *返 回 值：总重量 *作者：XXX 日期：2001/XX/XX *模块标识：SYSXXX-SUBXXX-MXXX ****************************************************************** *修改记录： 修改执行人： 修改日期：2001/XX/XX 修改说明：………… * *****************************************************************/ 注意：对于软件外包项目，红色部分不能出现，因为软件的产权不属于你。 原则2: 关于注释频率 说明 经验表明：注释占代码总量的30%左右，这样一个注释量能保证既清楚表达了程序员的意思，又不至于过分占用程序员的时间。 原则3: 注释是完善你的代码，而不是重复你的代码 说明 注释不应包含代码本身显而易见的信息，而应给出其他有用的信息。这些内容应是重要的，否则不如不加。 例子 // 这种注释没有用处 index++; // Increment index 原则4: 注释中的要尽量用通用术语 原则5:修改代码时，相应的注释要及时更新 原则6: 注释不要嵌套 例子 / * if (verbosity)0) { / * 这是嵌套注释* / cerr<<"Opening file<"<<filename<<">"<<end1; } * / 原则7: 区分段落注释和单行注释 说明 注释分段落和单行两大类： 1)段落注释用来说明一段代码，因而要放在该段代码之前。通常，此类注释较长(超过一行)，建议用户*/风格。 2)单行注释用来说明一句代码，通常放在该代码之后(行未注释)。建议用//风格。 段落注释用横线上下框住（见例子或附录的大段代码），目的是一目了然地将代码和注释区分出来，这样有利于代码和注释的阅读。 “战略性”注释的例子(格式) / * * This is "strategic" comment * used for block comments. * / 原则8: 避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释在公共制表位处对齐。 说明 一般从第46个字符位置开始：不同文件中可以不同，但同一个文件中最好保持一致。 原则9: 单独的注释行和被注释语句缩进相同的空格 原则10: 减少不必要的单独占一行的注释 原则11: 对每个引用的头文件给出行末注释 例子 #include〈iostream.h〉 // use cout，etc. #include〈pthread.h〉 // use POSIX thread library #include"ZDebug.hpp" // use macro Z_DEBUG() #include"ZErrLog.hpp" // use macro Z_L0G_...() #include"ZMutex.hpp" // use class Z_Mutex_T 原则12: 对每个空循环体给出确认性注释 例子 while (str[ctr++]!=EOS) { // This is an empty body } 原则13: 避免杂乱的注释，应该使用空白将注释同代码分开。 原则14: 避免在块注释的周围加上印刷框，难于维护。 原则15: 在部署发布之前，移除所有临时或无关的注释，以避免在日后的维护工作中产生混乱。 原则16: 如果需要用注释来解释复杂的代码节，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。 原则17: 在编写注释时使用完整的句子。注释应该阐明代码，而不应该增加多义性。 原则18: 在编写代码时立刻注释。 原则19: 避免多余的或不适当的注释。 原则20: 使用注释来解释代码的意图。它们不应作为代码的联机翻译。 原则21: 注释代码中不十分明显的任何内容。 原则22: 为了防止问题反复出现，对错误修复和解决方法代码总是使用注释，尤其是在团队环境中。 原则23: 对由循环和逻辑分支组成的代码使用注释。这是帮助源代码读者的主要方面。 原则24: 在整个应用程序中，使用具有一致的标点和结构的统一样式来构造注释。 原则25: 用空白将注释同注释分隔符分开。 原则26: 在所有的代码修改处加上修改标识的注释。 原则27: 为了是层次清晰，在闭合的右花括号后注释该闭合所对应的起点。 namespace Langchao.Procument.Web { } // namespace Langchao.Procument.Web