C 注释规范
C++注释规范
版本：1.0
制定部门：技术架构部C++基础架构组
2006.8
目录
1说明 (3)
2注释种类 (3)
2.1重复代码 (3)
2.2解释代码 (3)
2.3代码标记 (3)
2.4概述代码 (3)
2.5代码意图说明 (4)
2.6传达代码无法表达的信息 (4)
3注释原则 (4)
3.1站在读者的立场编写注释 (4)
3.2注释无法取代良好的编程风格 (4)
3.3好注释能在更高抽象层次上解释我们想干什么 (5)
4规范细则 (5)
4.1文件注释规范 (5)
4.2名字空间注释规范 (6)
4.3类定义注释规范 (7)
4.4数据声明注释规范 (8)
4.5函数注释规范 (8)
4.6代码标记注释规范 (10)
5FAQ (10)
5.1枚举值需要注释吗？ (10)
5.2前置条件、后置条件和不变式有必要注释出来吗？ (10)
5.3写注释太耗时间怎么办？ (11)
5.4有效的注释是指什么？ (11)
参考书目 (11)
参考工具 (11)
1说明
本文档用于规范C++代码中注释的编写。规范中提出的多数注释格式都来源于文档生成工具doxygen，所以遵从本规范进行注释的C++代码都可以使用doxygen生成美观一致的代码文档。
同时另一方面，美观绝非衡量文档质量的唯一标准。文档内容准确与否，是否充分，以及语言组织是否清晰流畅，这些都是决定一份文档质量的重要标准。遗憾的是，这些标准当中有不少需要通过主观加以判断，很难进行明确的规范。
所以我们将尽可能的提供明确的评判标准，同时，本规范中也不可避免的提出了一些比较主观的注释要求或是建议，这些要求或是建议多数都来自于众多先驱多年的开发经验。遵循它们不仅有助于生成一份美观的代码文档。更重要，依照这些要求和建议来编写注释，能够有效的帮助开发者在早期就反省自己设计的合理性，同时也为编写单元测试提供更多的帮助。
2注释种类
2.1重复代码
重复性注释只是用不同文字把代码的工作又描述一次。他除了给读者增加阅读量外，没有提供更多信息。
2.2解释代码
解释性注释通常用于解释复杂、敏感的代码块。在这些场合他们能派上用场，但通常正是因为代码含混不清，才体现出这类注释的价值。如果代码过于复杂而需要解释，最好是改进代码，而不是添加注释。使代码清晰后再使用概述性注释或者意图性注释。
2.3代码标记
标记性注释并非有意留在代码中，他提醒开发者某处的工作未做完。在实际工作中，我们经常会使用这些注释作为程序骨架的占位符，或是已知bug的标记。
2.4概述代码
概述性注释是这么做的：将若干代码行的意思以一两句话说出来。这种注释比重复性注释强多了，因为读者读注释能比读代码更快。概述性注释对于要修改你代码的其他人来说尤
其有用。
2.5代码意图说明
意图性注释用来指出要解决的问题，而非解决的方法。意图性注释和概述性注释没有明显的界限，其差异也无足轻重，都是非常有效的注释。
2.6传达代码无法表达的信息
某些信息不能通过代码来表达，但又必须包含在源代码中。这种注释包括版权声明、作者、日期、版本号等杂项信息；与代码设计有关的注意事项；优化注记；和doxygen要求的注释等等。
3注释原则
编写一份好的注释，并不比编写一段好的代码更容易，以至于我们不得不特别强调编写注释应该遵循的三个原则：
3.1站在读者的立场编写注释
我们的代码将会面对很多不同的读者。其中一类是代码复审者。他们希望看到的是准确的注释说明，小心地编写注释避免出现可笑的错误是最重要的。
接下来的读者是代码的用户，这部分人大多并不关心代码中使用了何等绝妙的高超技术。事实上，代码能干什么，以及如何正确的使用更令他们感兴趣。所以当我们在对那些可能面向用户的地方注释时，多多考虑一下用户的实际需要并非多余。
最后一类，怎么说呢，作为代码的维护者，他们整天要和成打的代码打交道，渴望能够用最少的时间找到目标代码。所以，如果代码中有一些提纲挈领的注释，可以供他们用作节约代码阅读时间的索引，毫无疑问，这会令大家都工作得更加开心。
3.2注释无法取代良好的编程风格
引用《代码大全》中的观点，在代码层文档中起主要作用的因素并非注释，而是良好的编程风格。编程风格包括良好的程序结构、直率易懂的方法、有意义的变量名和函数名、具名常量、清晰的布局、以及最低复杂度的控制流及数据结构。关于命名方面的规范参见《C++命名规范》。
虽然本篇规范讨论的重点并非编程风格，但是无论什么时候，我们都应该明白，对于精心编写的代码而言，注释不过是美丽衣裳上的小饰物而已。
3.3好注释能在更高抽象层次上解释我们想干什么
在编写注释这一问题上，我们经常犯的一个错误，就是将代码已经清楚说明的东西换种说法再写一次。尤其是如果我们为代码添加中文注释的时候，简单的等同于将英文译作中文，那么这样的注释能够给他人带来的好处微乎其微，更多时候是徒增阅读负担以及维护工作量。
再次重申，好注释不是重复代码，或是解释代码。它们会让其意图清晰。注释应该能在更高抽象层次上解释我们想干什么。
4规范细则
4.1文件注释规范
代码文件注释是典型的用于传达代码无法表达信息类的注释，所以没有太多值得讨论的地方。一份文件注释至少需要包括以下内容：
1)代码文件的文件名，占据注释的第一行并用@file加以标记
2)文件内容的简要描述，占据单独一行并用@brief加以标记
3)文件作者的公司email地址，占据单独一行并用@author加以标记
4)文件活动年份1，占据单独一行并用@date加以标记
也可以包含以下一些可选内容：
1)文件内容的详细描述，紧接简要描述之后并与其以一空行隔开
2)文件版本，占据单独一行并用@version加以标记，使用maj.min格式表示，其
中maj为主版本号，min为次版本号。
文件注释需要放到每个代码文件的起始位置。这里提供了一个完整的格式示例，多数情况下可以完全照搬其格式。
请注意，正如我们《C++编码规范》中提到的。在C++世界中，我们不应该使用C风格的/*…*/块注释，而应该使用C++风格的//行注释。是的，我们应该毫不动摇的恪守这一条
1所谓“文件活动年份”，可以把它理解为文件从创建年份到最后一次维护的年份，比如2004-2006。
款。但是，由于我们希望借助doxygen帮助我们生成漂亮的文档，如果我们在对文件注释的
为了避免这样的尴尬场面，我们只好破例留下了这段C风格文件注释。好在这是唯一必须使用C风格注释才能令doxygen满意的地方，跨过文件注释之后，我们仍然应该虔诚的遵循C++的行注释风格。
4.2名字空间注释规范
名字空间是一个好东西，编写名字空间注释的要点是，不要试图把这个名字空间介绍的面面俱到。简单的介绍设置这个名字空间的意图或是完全不要注释都是不错的选择。
如果决定要为名字空间添加注释，有一点非常重要：无论如何不要试图给同一个名字空间提供两份不同的注释，不管这些注释是否位于同一个代码文件中。一个有效的做法是，一开始不用给名字空间添加任何注释，先用doxygen生成文档，发现哪个名字空间缺少文档，再挑选一个最合适的代码文件进行名字空间注释。下面是一个名字空间注释的格式示例：
结合前面文件注释的例子我们可以看到，@brief概述项之后，必须有一个空行用于分割随后的详细描述。本文中所有的概述和详述项都遵循这一规则，后面将不再累述。
4.3类定义注释规范
类定义注释主要有以下几个用途：
?说明该类的设计方法。有的信息通过编码细节“逆向工程”是难以获得的，如果概述性注释能够提供这些信息，将会特别有用。在其中应该说明类的设计思
路、总体设计方法和曾考虑过后又放弃的其他方案等等。
?类使用指南。这主要是针对代码用户所做的注释，当看到一个类定义时，用户往往第一个念头就是想要知道这个类可以用来做什么，以及怎么才能正确地做
到。添加这样的注释，可以有效地帮助用户进入一些代码作者认为正确地使用
场景，而不是任凭用户自行想象，然后使用错误的方式来操作这个类。
?说明类不变项。类确保从调用者的视角来看，该条件总是为真。在类各个成员函数内部处理过程中，不变项不一定会保持，但在函数退出，控制权返回到调
用者时，不变项必须为真。
请注意，要想达到以上这些目标，使用重复代码的注释方式是不可能做到的。下面是我们一个类注释格式及演示如何达到第2、3两个个目标的例子：
请特别注意例子中注释的最后部分，使用@invariant指出的不变项，这一承诺将对类所有的方法有效。因此，单元测试的编写者将会非常乐意对这一承诺加以验证。
那么，是不是所有的类，我们都需要为其编写如此详尽细致的说明注释呢？事实上完全2@ref是doxygen中用于引用其他主题的特殊标签，本例中多处出现的引用都会指向一些方法说明。
没有必要。所谓使用指南，只有在别人有使用的需求且存在疑问，需要这些信息加以解答时才具有实际的意义。所以，对于大多数为了优化代码结构，或是为了实施某些设计模式而衍生出来，并不真正直接向外界提供功能的内部实现类而言，都不需要编写示例中那样太过详细的指南性质注释。这些类更需要的是说明该类设计方法的注释。
大致上我们认为只要满足下面列举的一些条件，就应该编写较为详细的指南性说明注释：
?概要设计中明确提出的接口类
?会被多人或是多处共享的工具类
?虽是局部使用，但结构复杂以至于很容易引起错误理解以至于需要特别说明4.4数据声明注释规范
数据声明包括类数据成员、具名常量和位标志。
变量声明的注释应给出变量名未表达出来的各种信息。研究表明，对数据进行注释比对使用数据的过程做注释更为重要（SDC1982）。下面是对数据进行注释的一些准则：?注释数值的单位。例如某个数值变量表示长度，请指明长度单位是英寸、英尺、米、千米还是毫米。不能认为单位是不言自明的——新手不知道，工作于另一
个系统的人也不知道。
?说明数值的允许范围。如果变量值有一个期望范围，就应该明确的说明这个范围。
我们约定，可以在一行以内容纳的数据声明注释，都应该使用行尾注释法，下面是一个变量声明注释的格式示例：
注意///之后的<小于号，这是行尾注释必须遵循的格式。
一行无法容纳的数据声明注释，则不采用行尾注释法。下面是一个多行注释的例子：
4.5函数注释规范
为一个函数编写注释，一般而言需要说明以下几个部分的信息：
a)函数的概要描述，使用@brief加以标识。注意如果一个函数无法用一两句话说清
楚，就有必要考虑我们到底想让函数做什么。要是不便做出简短的说明，往往意味着设计还嫌不足，这时就应该反思一下是否需要修正设计了。原则上除了简单的get/set访问器，其余所有的函数都应该附上概要说明。
b)通过函数名无法传达的信息，紧接概要描述之后，并与其以一空行隔开。如果函数
名和概要描述已经足够说明这个函数的一切，那么完全可以忽略这一部分。但有些时候我们希望告诉读者一些名称和标准功能之外的函数行为特征时，就可以将这些内容通过这种方式表达出来。这些内容很可能会描述一些函数精度局限性；是否以及如何对某一全局数据进行了修改；所使用算法的来源等等。
c)参数的描述，每个参数注释都使用@param加以标识。事实上，参数注释的内容和
前面介绍的数据注释非常类似，它们都用于给出名称未能表达的信息，比如单位等信息。只不过，对于函数注释而言，有专门的前置条件用于描述参数取值的范围限定。所以在参数注释中就不需要专门指出其取值范围。注意为参数加上输入/输出标记是必要的，这一指示通过紧接参数名的[in]/[out]来体现。
d)前置条件描述，在最后一个参数注释之后使用@pre加以标识。说到前置条件，这
在契约式编程中是很重要的概念。它是函数与其调用者之间制定的契约之一。前置条件规定了作为函数的调用者，必须遵循的一些调用规则，如果调用者违反的这些规则，那么函数将不会正确执行。正如前面提到，前置条件可以用于描述参数的取值范围。事实上，前置条件可以约定的规则远不止这一点，例如作为一个数据库数据检索函数，它可以在其前置条件中指出必须首先保证数据库连接是打开的等等。
前置条件不是函数注释中必须的选项，但是我们认为作为契约式编程实践的重要体现，尽量明确的为自己的函数构筑起防线是非常值得的事情。
e)返回值描述，在前置条件之后使用@return加以标识。对于返回值，我们需要以比
较简短的语言说明它的含义，同时也要注意是否存在单位等需要特别说明的附加信息。返回值描述比较特殊的一个地方在于，如果返回值的值本身有一个确定的取值范围，并且应该分项说明的话，可以使用@retval标记，对每个可能返回的值加以说明。如果函数没有返回值或是返回值为void，则可以忽略本项内容。
f)后置条件描述，在返回值描述之后使用@post加以标识。与前置条件相对应，后置
条件用于向函数调用者承诺函数保证会做到的事情，以及函数执行完成时世界的状态。一个函数具有后条件这一事实同时也意味着它会结束：不可能出现无限循环。
同前置条件一样，后置条件同样不是必须的选项，但这并不意味着其可有可无。下面是一个包含了上述所有内容的成员函数注释示例：
4.6代码标记注释规范
在代码编写过程中，经常需要在尚未完成的代码骨架中加入一些警示标记，或是当发现程序某处存在bug时加以标注以备随后修正。糟糕的是，不同的程序员可能会使用不同的方式来表达他们的意图，这导致维护难度增加以及很难使用工具检测。所以需要我们以一种统一且使用工具容易检测的方式来进行代码标记。
标注计划中需要完成的代码，我们可以在准备添加代码的地方使用@todo标记，这样不但在doxygen生成的文档中会醒目的表现出来，而且很多编辑器也能够识别这一标记，在特定的位置提示你将要进行的工作。类似的，为了指示已知bug，我们可以使用@bug标记。
5FAQ
5.1枚举值需要注释吗？
事实上，枚举值本身就是对一些原本是字面常量值的特殊注释。下面是我们经常可以看
显然，这样画蛇添足地重复代码的注释毫无意义。请记住，枚举值本身就是说明，取一个合理的好名字远胜于添加一段无谓的注释。与之类似的还有typedef，在是否需要注释这个问题上，他们具有类似的特征。
5.2前置条件、后置条件和不变式有必要注释出来吗？
其实，采用注释来表现程序契约纯属无奈之举。原因很简单，C++语言本身并不支持程序契约的表达。可是经验证明，按合约设计的程序，在交付后产生问题的可能性远远小于没
有明确约束的。
尽管借助C++编译器无法执行这些契约，但是至少我们可以通过编写注释，以一种语言提醒的方式对这一缺陷加以弥补。有一个可行的途径总好过一无所有不是吗。
5.3写注释太耗时间怎么办？
有效注释并不费时。注释太多并不比注释太少好，
注释占用太多时间通常归因于两点。
一是注释风格耗时或枯燥乏味。我们在制定规范时对此进行了充分考虑，在编写便利和符合doxygen要求之间作了很多平衡。
二是因为不容易想出程序干什么的描述，所以写注释太难。这通常意味着还没有真正的理解程序。“写注释”所占用的时间其实都用在了更好地理解程序上面，不管写不写注释，这些时间注定是要花的。
5.4有效的注释是指什么？
参考前文中提到的注释分类，我们认为，对于已经发布的代码，只允许有三种类型的注释：代码无法表达的信息、意图性注释和概述性注释。
特别需要注意的是，重复代码性质的注释，无论如何都不能称为好注释。编写这样的注释只会给人带来阅读和维护的负担。
参考书目
[McConnell04]Steve McConnell.CODE COMPLETE(2nd Edition)(Microsoft Press2006) [Hunt-Thomas04]A.Hunt and D.Thomas.The Pragmatic Programmer(Addison Wesley2004) [Doxygen06]Doxygen manual1.4.7(Doxygen2006)
参考工具
[Doxygen]Doxygen1.4.7
C语言注释规范
C语言注释规范 1.注释原则 同一软件项目开发中，尽量保持代码注释规范和统一。 注释方便了代码的阅读和维护。 边写代码边注释，修改代码时要相应修改注释，保证注释和代码的一致性。 注释要简洁明确，不要出现形容词。 对于写的好的注释，我们将是第一个受益者。 大型软件开发中，通过别人的注释可以快速知道他人所写函数的功能，返回值，参数的使用。 2.文件头部的注释 示例： / * Program Assignment : 该文件的作用 * Author: 作者 * Date: 2013/8/6 14:34 * Description: 该文件的描述 *****/ /* * Source code in : 源代码的路径 * Function List: * initLinear 初始化线性表 * destoryLinear 释放线性表申请的空间 * isLinearEmpty 判断线性表是否为空 * isLinearFull 判断线性表是否为满 * getLinearElementValue 取得下标为index的元素的值 */ 注意：这个函数列表可以快速查询到我们想要了解的函数。 3.结构体，全局变量等的注释 示例： typedef POLYNOMIAL USER_TYPE; /* 新的数据类型的描述*/ int a; /* 全局变量的作用*/ /* 说明结构体的功能*/ typedef struct LINEAR { USER_TYPE *data; /* 每个成员的意义(作用) */ int maxRoom; /* 每个成员的意义(作用) */
int elementCount; /* 每个成员的意义(作用) */ }LINEAR; 4.函数的注释 在逻辑性较强的的地方加入注释，以便其他人的理解，在一定的程度上排除bug。 示例： /* * Function Name: getLinearElementIndex * Purpose: 取得元素的index值 * Params : * @LINEAR linear 线性表实例 * @USER_TYPE var 类型为USER_TYPE的实例 * @int (*)() cmp 提供接口，让用户定义具体比较函数 * Return: int 返回元素的index值 * Limitation: 如果返回-1，则代表不存在var的元素 */ int getLinearElementIndex(LINEAR linear, USER_TYPE var, int (*cmp)()) { /* * 如果逻辑太过复杂，这里写明该算法的过程和思路。 */ boolean found = FALSE; int i; for(i = 0; i < && !found; i++) if(cmp[i], var) == 0) found = TRUE; if(i >= i = NOT_FOUND; return i; }
程序代码注释编写规范
程序代码注释编写规范 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始，任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始，以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************ COPYRIGHT (C), MicTiVo International. Co., Ltd. FileName: Author:
程序代码注释编写规范
百度文库- 让每个人平等地提升自我 1 程序代码注释编写规范 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* (C), MicTiVo International. Co., Ltd. 1.File : . History: Date: Author: Modification: 2. .. *************************************************/ 一、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************ (C), MicTiVo International. Co., Ltd. FileName: Author: Version : Date: : / /*receive _process() */ 意:与溢出中断写初值不同}
程序代码注释编写规范
程序代码注释编写规范 XXX份公司
为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始，任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始，以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************
C语言编写规范之注释
1、头文件包含Includes 2、私有类型定义 Private typedef 3、私有定义Private define 4、私有宏定义 Private macro 5、私有变量 Private variables 6、私有函数原型Private function prototypes 7、私有函数Private functions 8、私有函数前注释 /****************************************************************************** * * Function Name : FSMC_NOR_Init * Description : Configures the FSMC and GPIOs to interface with the NOR memory. * This function must be called before any write/read operation * on the NOR. * Input : None * Output : None * Return : None ******************************************************************************* / 9、程序块采用缩进风格编写，缩进空格为4。 10、相对独立的程序块之间、变量说明之后必须加空行； 11、较长的字符（>80字符）要分成多行书写，长表达式要在低优先级操作符划分新行，操作符放在新行之首，新行要恰当缩进，保持排版整齐； 12、循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首; 13、若函数或过程中的参数较长，则要进行适当的划分。 14、不允许把多个短语句写在一行中，即一行只写一条语句。 15、if、for、do、while、case、switch、default等语句自占一行，且if、for、 do、while等语句的执行语句部分无论多少都要加括号{}。 16、对齐只使用空格键，不使用TAB键； 17、 函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case 语句下的情况处理语句也要遵从语句缩进要求 18、 程序块的分界符（如C/C++语言的大括号‘{’和‘}’）应各独占一行并且位于同一 列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以 及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。 19、 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或
代码规范
目录 一．规范简介 1.1 目的 所有的程序开发手册都包含了各种规则。一些习惯自由程序人员可能对这些规则很不适应，但是在多个开发人员共同写作的情况下，这些规则是必需的。这不仅仅是为了开发效率来考虑，而且也是为了后期维护考虑。 本规范正是为培养规范设计和编程，养成良好的习惯，增强软件产品的稳定，健壮，可靠性；同时也为了提高软件的可读性，可以让程序员尽快而彻底地理解新的代码，使产品可维护性提高而制定的规范。 1.2 开发规范的重要性 （1）减少维护成本； 一个软件的生命周期中，80%的花费在于维护，另一方面，几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护，规范的编码减少人员变动带来的维护成本。 （2）改善软件的可读性 可以让程序员尽快而彻底地理解新的代码。在一个团队中，代码也容易在程序员之间共享。 （3）维护部门交付产品的规范形象。 二．具体规范 2.1 注释 注释是软件可读性的具体表现。程序注释量一般占程序编码量的20%，软件工程要求不少于20%。程序注释不能用抽象的语言，要精确表达出程序的处理说明。避免每行程序都使用注释，可以在一段程序的前面加一段注释，具有明确的处理逻辑。 注释必不可少，但也不应过多，不要被动得为写注释而写注释。
2.1.1 需要注释的部分 （1）文件头注释，文件创建及修改记录，版权归属，作者以及修订者，以及对文件的简短描述。 （2）类的目的（即类所完成的功能）、设置接口的目的以及应如何被使用。 （3）成员方法注释（对于设置与获取成员方法，在成员变量已有说明的情况下，可以不加注释；普通成员方法要求说明完成功能，参数含义以及返回值）。 （4）普通成员方法内部注释（控制结构、代码所起到的作用以及如此编写代码的原因，处理顺序等）。 （4）参数的含义以及其他任何约束或前提条件、字段或属性描述。而对于局部变量，如无特别意义的情况下则不加注释。 2.1.2 具体注释 （1）文件头注释 要求：遵循JavaDoc的规范，在每一个源文件的开头注明该文件的作用, 作简要说明, 并写上源文件的作者,版权信息编写日期。如果是修改别人编写的源文件，要在修改信息上注明修改者和修改日期。 例子： /** * @Title: 文件名 * @Copyright (C) 年份龙图软件 * @Description: 文件信息描述 * @Revision History: * @Revision 版本号日期作者. */ （2）类和接口的注释 要求：遵循JavaDoc的规范，在每一个类的开头注明该类的作用，作简要说明，并写上作者，编写日期。 例子： /** * @ClassName: 类（或接口）名 * @Description: Description of this class
程序源代码注释规范
程序注释规范说明 程序注释规范应包括以下三方面： 一、文件头部注释 在代码文件的头部进行注释，这样做的好处在于，我们能对代码文件做变更跟踪。在代码头部分标注出创始人、创始时间、修改人、修改时间、代码的功能，这在团队开发中必不可少，它们可以使后来维护/修改的同伴在遇到问题时，在第一时间知道他应该向谁去寻求帮助，并且知道这个文件经历了多少次迭代、经历了多少个程序员的开发和修改。 样本： /***************************************************** ** 作者：Liuchao ** 创始时间：2007-11-12 ** 修改人：Liuchao ** 修改时间：2007-11-12 ** 修改人：Liaochao ** 修改时间：2007-11-12 ** 描述： ** 主要用于产品信息的资料录入，… *****************************************************/ 二、函数、属性、类等注释 请使用///三斜线注释，这种注释是基于XML的，不仅能导出XML制作帮助文档，而且在各个函数、属性、类等的使用中，编辑环境会自动带出注释，方便你的开发。以protected，protected Internal，public声明的定义注释都建议以这样命名方法。 例如： ///
/// 用于从ERP系统中捞出产品信息的类 /// class ProductTypeCollector { … } 三、逻辑点注释 在我们认为逻辑性较强的地方加入注释，说明这段程序的逻辑是怎样的，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG。在注释中写明我们的逻辑思想，对照程序，判断程序是否符合我们的初衷，如果不是，则我们应该仔细思考耀修改的是注释还是程序了… 四、变量注释 我们在认为重要的变量后加以注释，说明变量的含义，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG.我们常用///三斜线注释。 /// 用于从ERP系统中捞出产品信息的类 class ProductTypeCollector { int STData;///
java注释规范总结大全
在软件开发的过程中总是强调注释的规范，但是没有一个具体的标准进行说明，通常都是在代码编写规范中简单的描述几句，不能作为一个代码注释检查的标准和依据，做什么都要有一个依据吗:),现在我特整理了一个《Java的注释规范》，内容来自网络、书籍和自己的实际积累。 JA V A注释规范 版本/状态作者版本日期 1.0 ghc 2008-07-02 一、背景 1、当我们第一次接触某段代码，但又被要求在极短的时间内有效地分析这段代码，我们需要什么样的注释信息？ 2、怎么样避免我们的注释冗长而且凌乱不堪呢？ 3、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？ 二、意义 程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本, 并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力。 三、注释的原则 1、注释形式统一 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。 2、注释的简洁 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。 3、注释的一致性 在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保证代码与注释的同步。 4、注释的位置 保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。 5、注释的数量 注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动的为写注释而写注释。 6、删除无用注释
代码编写规范说明书
代码编写规范说明书（c#.net与https://www.sodocs.net/doc/4b2179305.html,）目录 1 目的 2 范围 3 注释规范 3.1 概述 3.2 自建代码文件注释 3.3 模块（类）注释 3.4 类属性注释 3.5 方法注释 3.6 代码间注释 4 命名总体规则 5 命名规范 5.1 变量（Variable）命名 5.2 常量命名 5.3 类（Class）命名 5.4 接口（Interface）命名 5.5 方法（Method）命名 5.6 名称空间Namespace）命名 6 编码规则 6.1 错误检查规则 6.2 大括号规则 6.3 缩进规则 6.4 小括号规则 6.5 If Then Else规则 6.6 比较规则 6.7 Case规则 6.8 对齐规则 6.9 单语句规则 6.10 单一功能规则 6.11 简单功能规则 6.12 明确条件规则 6.13 选用FALSE规则 6.14 独立赋值规则 6.15 定义常量规则 6.16 模块化规则 6.17 交流规则 7 编程准则 7.1 变量使用 7.2 数据库操作 7.3 对象使用 7.4 模块设计原则 7.5 结构化要求 7.6 函数返回值原则 8 代码包规范 8.1 代码包的版本号
8.2 代码包的标识 9 代码的控制 9.1 代码库/目录的建立 9.2 代码归档 10 输入控制校验规则 10.1 登陆控制 10.2 数据录入控制 附件1：数据类型缩写表 附件2：服务器控件名缩写表 1 目的 一.为了统一公司软件开发设计过程的编程规范 二.使网站开发人员能很方便的理解每个目录,变量，控件，类，方法的意义 三.为了保证编写出的程序都符合相同的规范，保证一致性、统一性而建立的程序编码规范。 四.编码规范和约定必须能明显改善代码可读性，并有助于代码管理、分类范围适用于企业所有基于.NET平台的软件开发工作 2 范围 本规范适用于开发组全体人员，作用于软件项目开发的代码编写阶段和后期维护阶段。 3 注释规范 3.1 概述 a) 注释要求英文及英文的标点符号。 b) 注释中，应标明对象的完整的名称及其用途，但应避免对代码过于详细的描述。 c) 每行注释的最大长度为100个字符。 d) 将注释与注释分隔符用一个空格分开。 e) 不允许给注释加外框。 f) 编码的同时书写注释。 g) 重要变量必须有注释。 h) 变量注释和变量在同一行，所有注释必须对齐，与变量分开至少四个“空格”键。 如：int m_iLevel,m_iCount; // m_iLevel ....tree level // m_iCount ....count of tree items string m_strSql; //SQL i) 典型算法必须有注释。 j) 在循环和逻辑分支地方的上行必须就近书写注释。 k) 程序段或语句的注释在程序段或语句的上一行 l) 在代码交付之前，必须删掉临时的或无关的注释。 m) 为便于阅读代码，每行代码的长度应少于100个字符。 3.2 自建代码文件注释 对于自己创建的代码文件（如函数、脚本），在文件开头，一般编写如下注释： /****************************************************** FileName: Copyright (c) 2004-xxxx *********公司技术开发部 Writer: create Date: Rewriter:
代码注释规范说明
Comments criterion of the Code 在多个PROJIECT共同开发的前提下，为了减少修改升级CODE过程中出现失误和方便SI 人员对代码的维护，加强部门整体代码注释规范，建议通过在每一次代码修改过程中添加代码标志符进行注释，这样可以使软件工程师在升级代码的过程中减少错误率，同时可以保持对以前版本代码的修改思路清晰，能在最短时间里复查代码中的错误。 标准C++/C的文件结构： // Copyright (c) Microsoft Corporation. All rights reserved. // Use of this source code is subject to the terms of the Microsoft end-user // license agreement (EULA) under which you licensed this SOFTWARE PRODUCT. // If you did not accept the terms of the EULA, you are not authorized to use // this source code. For a copy of the EULA, please see the LICENSE.RTF on your // install media. /** * Port Copyright (c) Hisys Corporation. All rights reserved. * @file batt_pdd.c * Abstract * This file contains battery driver PDD implementation. * Change Log * 2006.2.21 Shi Yuehua Initial Version * **/ 代码注释规范如下： //***********COMMENTS-HISTORY***********// /****************************************************************************** *NAME | SIGN | PROJECT | SUMMARY * *------------------------------------------------------------------------------ *Johson.Li M060806_A HXS006 Use the two methods to measure the battery voltage. *Johson.Li M060812_A HXS010 Change the init array value from 4 to 8. *Johson.Li M060812_B COMMON Change the USB CHANGING conditions. * ........... * ........... ******************************************************************************/ 代码注释标题声明包含四部分： 1.作者名称 2.标记符 3.项目名称 4.摘要 1.《NAME》：修改该部分CODE的软件人员名称（英文名称&中文名称拼音缩写），第一个字母大写。 2．《SIGN》：该标记符应在所有本次修改代码前面声明，主要是为了方便搜索，当我们想查找本次为了实现某个功能所做的代码修改时，可以搜索此标记符，即可找到全部修改过的相关代码段。 标记符：M060806_A M: 英文
C 注释规范
C++注释规范 版本：1.0 制定部门：技术架构部C++基础架构组 2006.8
目录 1说明 (3) 2注释种类 (3) 2.1重复代码 (3) 2.2解释代码 (3) 2.3代码标记 (3) 2.4概述代码 (3) 2.5代码意图说明 (4) 2.6传达代码无法表达的信息 (4) 3注释原则 (4) 3.1站在读者的立场编写注释 (4) 3.2注释无法取代良好的编程风格 (4) 3.3好注释能在更高抽象层次上解释我们想干什么 (5) 4规范细则 (5) 4.1文件注释规范 (5) 4.2名字空间注释规范 (6) 4.3类定义注释规范 (7) 4.4数据声明注释规范 (8) 4.5函数注释规范 (8) 4.6代码标记注释规范 (10) 5FAQ (10) 5.1枚举值需要注释吗？ (10) 5.2前置条件、后置条件和不变式有必要注释出来吗？ (10) 5.3写注释太耗时间怎么办？ (11) 5.4有效的注释是指什么？ (11) 参考书目 (11) 参考工具 (11)
1说明 本文档用于规范C++代码中注释的编写。规范中提出的多数注释格式都来源于文档生成工具doxygen，所以遵从本规范进行注释的C++代码都可以使用doxygen生成美观一致的代码文档。 同时另一方面，美观绝非衡量文档质量的唯一标准。文档内容准确与否，是否充分，以及语言组织是否清晰流畅，这些都是决定一份文档质量的重要标准。遗憾的是，这些标准当中有不少需要通过主观加以判断，很难进行明确的规范。 所以我们将尽可能的提供明确的评判标准，同时，本规范中也不可避免的提出了一些比较主观的注释要求或是建议，这些要求或是建议多数都来自于众多先驱多年的开发经验。遵循它们不仅有助于生成一份美观的代码文档。更重要，依照这些要求和建议来编写注释，能够有效的帮助开发者在早期就反省自己设计的合理性，同时也为编写单元测试提供更多的帮助。 2注释种类 2.1重复代码 重复性注释只是用不同文字把代码的工作又描述一次。他除了给读者增加阅读量外，没有提供更多信息。 2.2解释代码 解释性注释通常用于解释复杂、敏感的代码块。在这些场合他们能派上用场，但通常正是因为代码含混不清，才体现出这类注释的价值。如果代码过于复杂而需要解释，最好是改进代码，而不是添加注释。使代码清晰后再使用概述性注释或者意图性注释。 2.3代码标记 标记性注释并非有意留在代码中，他提醒开发者某处的工作未做完。在实际工作中，我们经常会使用这些注释作为程序骨架的占位符，或是已知bug的标记。 2.4概述代码 概述性注释是这么做的：将若干代码行的意思以一两句话说出来。这种注释比重复性注释强多了，因为读者读注释能比读代码更快。概述性注释对于要修改你代码的其他人来说尤
华为代码规范文档
代码规范文档
目录 1 概述错误!未定义书签。 编写目的错误!未定义书签。 文档约定错误!未定义书签。 预期的读者和阅读建议错误!未定义书签。 参考文献错误!未定义书签。 2 排版要求错误!未定义书签。 程序块缩进错误!未定义书签。 程序块之间空行错误!未定义书签。 长语句和长表达式错误!未定义书签。 循环、判断等长表达式或语句错误!未定义书签。 长参数错误!未定义书签。 短语句错误!未定义书签。 条件、循环语句错误!未定义书签。 语句对齐错误!未定义书签。 函数、过程和结构等语句块错误!未定义书签。 程序块分界符错误!未定义书签。 操作符前后空格错误!未定义书签。 其他错误!未定义书签。 3 注释错误!未定义书签。 有效注释量错误!未定义书签。 公司标识错误!未定义书签。 说明性文件错误!未定义书签。 源文件头错误!未定义书签。 函数头部说明错误!未定义书签。 注释与代码一致错误!未定义书签。 注释内容错误!未定义书签。 注释缩写错误!未定义书签。 注释位置错误!未定义书签。 变量、常量注释错误!未定义书签。 数据结构的注释错误!未定义书签。 全局变量错误!未定义书签。 注释缩排错误!未定义书签。 注释与代码之间空行错误!未定义书签。 变量定义、分支语句错误!未定义书签。 其他错误!未定义书签。 4 标识符命名错误!未定义书签。 命名清晰错误!未定义书签。 特殊命名需注释错误!未定义书签。 命名风格保持一致错误!未定义书签。 变量命名错误!未定义书签。 命名规范与系统风格一致错误!未定义书签。 其他错误!未定义书签。 5 可读性错误!未定义书签。 运算符优先级错误!未定义书签。
JAVA代码注释规范
JAVA代码注释规范 目录 JA V A代码注释规范 (1) 注释的原则 (1) 注释的简洁 (1) 注释的一致性 (1) 注释的位置 (2) 注释的数量 (2) 删除无用注释 (2) 复杂的注释 (2) 多余的注释 (2) 必加的注释 (3) JA V A注释技巧 (3) JA V A注释具体实现 (4) 源文件注释 (4) 类（模块）注释： (5) 接口注释： (5) 构造函数注释： (6) 方法注释： (6) 方法内部注释： (7) 全局变量注释： (7) 局部（中间）变量注释： (7) 常量 (7) p.s. 注释使用统一的注释文件 (8) 注释的原则 注释形式统一 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同， 按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。 注释的简洁 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。 注释的一致性
在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码， 在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建， 提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保证代码与注释的同步。 注释的位置 保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。 避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。 注释的数量 注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”，而不是文档， 程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动的为写注释而写注释。 删除无用注释 在代码交付或部署发布之前，必须删掉临时的或无关的注释，以避免在日后的维护工作中产生混乱。 复杂的注释 如果需要用注释来解释复杂的代码，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。 尽管一般不应该为了使代码更简单便于使用而牺牲性能，但必须保持性能和可维护性之间的平衡。 多余的注释 描述程序功能和程序各组成部分相互关系的高级注释是最有用的，而逐行解释程序如何工作的低级注释则不利于读、写和修改，是不必要的， 也是难以维护的。避免每行代码都使用注释。如果代码本来就是清楚、一目了然的则不加注释，避免多余的或不适当的注释出现。
程序代码注释编写规范
优梦优程序代码注释编写规范（试行） 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 一、注释条件： 1、基本注释（必须加） (a) 类（接口）的注释 (b) 构造函数的注释 (c) 方法的注释 (d) 全局变量的注释 (e) 字段/属性的注释 备注：简单的代码做简单注释，注释内容不大于10个字即可，另外，持久化对象或VO对象的getter、setter方法不需加注释。具体的注释格式请参考下面举例。 2、特殊必加注释（必须加）
(a) 典型算法必须有注释。 (b) 在代码不明晰处必须有注释。 (c) 在代码修改处加上修改标识的注释。 (d) 在循环和逻辑分支组成的代码中加注释。 (e) 为他人提供的接口必须加详细注释。 备注：此类注释格式暂无举例。具体的注释格式自行定义，要求注释内容准确简洁。 二、注释格式： 1、单行(single-line)注释：“//……” 2、块(block)注释：“/*……*/” 3、文档注释：“/**……*/” 4、javadoc 注释标签语法 @author 对类的说明标明开发该类模块的作者 @version 对类的说明标明该类模块的版本 @see 对类、属性、方法的说明参考转向，也就是相关主题 @param 对方法的说明对方法中某参数的说明 @return 对方法的说明对方法返回值的说明 @exception 对方法的说明对方法可能抛出的异常进行说明
代码审查规范方案
代码审查规范 1. Code Review目的 Code Review是一种用来确认方案设计和代码实现的质量保证机制，通过这个机制我们可以对代码、测试过程和注释进行检查。 Code Review主要用来在软件工程过程中改进代码质量，通过Code Review可以达到如下目的： ?在项目早期就能够发现代码中的BUG。 ?帮助初级开发人员学习高级开发人员的经验，达到知识共享。 ?避免开发人员犯一些很常见，很普通的错误。 ?保证项目组人员的良好沟通。 ?项目或产品的代码更容易维护。 2. Code Review的前提条件 代码提交审核前，开发者必须确保代码符合如下条件，审核者需要确保所有前提条件都已满足方可开始审查，同时也是审查的主要检查点。 ?所有代码注释清晰，语法正确，编译通过。 ?日志代码完整，业务日志、系统日志分开，中文描述，脱敏处理，状态变更，全部清晰明确。 ?测试代码覆盖全部分支和流程，暂时统一使用工具Emma（各编译器可下载对应插件）进行Coverage Check。
?项目引用关系明确，依赖关系清晰，配置文件描述。 3. Code Review的审查范围 代码的一致性、编码风格、代码的安全问题、脱敏问题、代码冗余、是否正确设计以符合设计要求（性能、功能）与设计文档相同等等。 3.1、完整性检查（Completeness） ?代码是否完全实现了设计文档中所涉及的所有流程和功能点 ?代码是否已包含所有所需的业务日志、系统日志、异常日志，日志内容是否完整，日志文件配置是否正确。 ?代码是否使用缓存等，配置信息是否正确可配置。 ?代码中是否存在任何没有定义或没有引用到的变量、常数或数据类型等 3.2、一致性检查（Consistency） ?代码的逻辑是否符合设计文档 ?代码中使用的格式、符号、结构等风格是否保持一致 3.3、正确性检查（Correctness） ?代码是否符合制定的标准 ?所有的变量都被正确定义和使用 ?所有的注释都是准确的 ?所有的程序调用都使用了正确的参数个数
Java注释规范整理
Java注释规范 一、背景 1、当我们第一次接触某段代码，但又被要求在极短的时间内有效地分 析这段代码，我们需要什么样的注释信息？ 2、怎么样避免我们的注释冗长而且凌乱不堪呢？ 3、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？ 二、意义 程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思 想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个 软件的维护成本 , 并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以让开发人员 尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合 作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼 出更加严谨的思维能力。 三、注释的原则 1、注释形式统一 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。 2、注释的简洁 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。 3、注释的一致性 在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后 或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保 证代码与注释的同步。 4、注释的位置 保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释； 行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这 种情况下，将所有行尾注释要对齐。 5、注释的数量 注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”，而不是文档，程序中的 注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动 的为写注释而写注释。 6、删除无用注释
程序编写规范(注释、命名等)
程序编写规范----注释、缩进、命名规范[复制链接] 一、注释 程序中的注释能够帮助理解程序。但是也不能太多，太多同样会影响程序的可读性。要遵循简练，准确，易理解的原则。 1、文件头：文件的头部应该有个对本文件的详细描述。内容包括版权，版本号，生成日期，作者，内容，功能，函数功能，与其他文件的关系，修改日志等。尤其是每次修改，都应该写入修改日志。 下面是一个常用的模版 /************************************************* Copyright (C), 2000-2004, ****** File name: // 文件名 Author: Version: Date: // 作者、版本及完成日期 Description: // 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1. .... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. ... *************************************************/ 2、函数：列出函数的目的，功能、输入输出、返回值、调用关系等。 模版： /************************************************* Function: // 函数名称 Description: // 函数功能、性能等的描述 Calls: // 被本函数调用的函数清单 Called By: // 调用本函数的函数清单 Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序） Table Updated: // 被修改的表（此项仅对于牵扯到数据库操作的程序） Input: // 输入参数说明，包括每个参数的作 // 用、取值说明及参数间关系。 Output: // 对输出参数的说明。 Return: // 函数返回值的说明