编程规范与范例(1).htm

编程规范与范例。从网上收集的

&nbsp;&nbsp;Input:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;输入参数说明，包括每个参数的作<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;用、取值说明及参数间关系。<br>
&nbsp;&nbsp;Output:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;对输出参数的说明。<br>
&nbsp;&nbsp;Return:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;函数返回值的说明<br>
&nbsp;&nbsp;Others:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;其它说明<br>
*************************************************/<br>
&amp;sup1;&nbsp;2-5：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。<br>
&amp;sup1;&nbsp;2-6：注释的内容要清楚、明了，含义准确，防止注释二义性。<br>
说明：错误的注释不但无益反而有害。<br>
规则2-7：避免在注释中使用缩写，特别是非常用缩写。<br>
说明：在使用缩写时或之前，应对缩写进行必要的说明。<br>
&amp;sup1;&nbsp;2-8：注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。<br>
示例：如下例子不符合规范。<br>
例1：<br>
/*&nbsp;get&nbsp;replicate&nbsp;sub&nbsp;system&nbsp;index&nbsp;and&nbsp;net&nbsp;indicator&nbsp;*/<br>
<br>
<br>
repssn_ind&nbsp;=&nbsp;ssn_data[index].repssn_index;<br>
repssn_ni&nbsp;=&nbsp;ssn_data[index].ni;<br>
<br>
例2：<br>
repssn_ind&nbsp;=&nbsp;ssn_data[index].repssn_index;<br>
repssn_ni&nbsp;=&nbsp;ssn_data[index].ni;<br>
/*&nbsp;get&nbsp;replicate&nbsp;sub&nbsp;system&nbsp;index&nbsp;and&nbsp;net&nbsp;indicator&nbsp;*/<br>
<br>
应如下书写<br>
/*&nbsp;get&nbsp;replicate&nbsp;sub&nbsp;system&nbsp;index&nbsp;and&nbsp;net&nbsp;indicator&nbsp;*/<br>
repssn_ind&nbsp;=&nbsp;ssn_data[index].repssn_index;<br>
repssn_ni&nbsp;=&nbsp;ssn_data[index].ni;<br>
&amp;sup1;&nbsp;2-9：对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。<br>
示例：<br>
/*&nbsp;active&nbsp;statistic&nbsp;task&nbsp;number&nbsp;*/<br>
#define&nbsp;MAX_ACT_TASK_NUMBER&nbsp;1000<br>
<br>
#define&nbsp;MAX_ACT_TASK_NUMBER&nbsp;1000&nbsp;/*&nbsp;active&nbsp;statistic&nbsp;task&nbsp;number&nbsp;*/<br>
&amp;sup1;&nbsp;2-10：数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。<br>
示例：可按如下形式说明枚举/数据/联合结构。<br>
/*&nbsp;sccp&nbsp;interface&nbsp;with&nbsp;sccp&nbsp;user&nbsp;primitive&nbsp;message&nbsp;name&nbsp;*/<br>
enum&nbsp;&nbsp;SCCP_USER_PRIMITIVE<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;N_UNITDATA_IND,&nbsp;/*&nbsp;sccp&nbsp;notify&nbsp;sccp&nbsp;user&nbsp;unit&nbsp;data&nbsp;come&nbsp;*/<br>
&nbsp;&nbsp;&nbsp;&nbsp;N_NOTICE_IND,&nbsp;&nbsp;&nbsp;/*&nbsp;sccp&nbsp;notify&nbsp;user&nbsp;the&nbsp;No.7&nbsp;network&nbsp;can&nbsp;not&nbsp;*/<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;transmission&nbsp;this&nbsp;message&nbsp;*/<br>
&nbsp;&nbsp;&nbsp;&nbsp;N_UNITDATA_REQ,&nbsp;/*&nbsp;sccp&nbsp;user's&nbsp;unit&nbsp;data&nbsp;transmission&nbsp;request*/<br>
};<br>
&amp;sup1;&nbsp;2-11：全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。<br>
示例：<br>
/*&nbsp;The&nbsp;ErrorCode&nbsp;when&nbsp;SCCP&nbsp;translate&nbsp;*/<br>
/*&nbsp;Global&nbsp;Title&nbsp;failure,&nbsp;as&nbsp;follows&nbsp;*/&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;变量作用、含义<br>
/*&nbsp;0&nbsp;－&nbsp;SUCCESS&nbsp;&nbsp;&nbsp;1&nbsp;－&nbsp;GT&nbsp;Table&nbsp;error&nbsp;*/<br>
/*&nbsp;2&nbsp;－&nbsp;GT&nbsp;error&nbsp;&nbsp;Others&nbsp;－&nbsp;no&nbsp;use&nbsp;&nbsp;*/&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;变量取值范围<br>
/*&nbsp;only&nbsp;&nbsp;function&nbsp;&nbsp;SCCPTranslate()&nbsp;in&nbsp;*/<br>
/*&nbsp;this&nbsp;modual&nbsp;can&nbsp;modify&nbsp;it,&nbsp;&nbsp;and&nbsp;&nbsp;other&nbsp;*/<br>
/*&nbsp;module&nbsp;can&nbsp;visit&nbsp;it&nbsp;through&nbsp;call&nbsp;*/<br>
/*&nbsp;the&nbsp;&nbsp;function&nbsp;GetGTTransErrorCode()&nbsp;*/&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;使用方法<br>
BYTE&nbsp;g_GTTranErrorCode;&nbsp;&nbsp;<br>
&amp;sup1;&nbsp;2-12：注释与所描述内容进行同样的缩排。<br>
说明：可使程序排版整齐，并方便注释的阅读与理解。<br>
示例：如下例子，排版不整齐，阅读稍感不方便。<br>
void&nbsp;example_fun(&nbsp;void&nbsp;)<br>
{<br>
/*&nbsp;code&nbsp;one&nbsp;comments&nbsp;*/<br>
&nbsp;&nbsp;&nbsp;&nbsp;CodeBlock&nbsp;One<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;code&nbsp;two&nbsp;comments&nbsp;*/<br>
&nbsp;&nbsp;&nbsp;&nbsp;CodeBlock&nbsp;Two<br>
}<br>
<br>
应改为如下布局。<br>
void&nbsp;example_fun(&nbsp;void&nbsp;)<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;code&nbsp;one&nbsp;comments&nbsp;*/<br>
&nbsp;&nbsp;&nbsp;&nbsp;CodeBlock&nbsp;One<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;code&nbsp;two&nbsp;comments&nbsp;*/<br>
&nbsp;&nbsp;&nbsp;&nbsp;CodeBlock&nbsp;Two<br>
}<br>
&amp;sup1;&nbsp;2-13：将注释与其上面的代码用空行隔开。<br>
示例：如下例子，显得代码过于紧凑。<br>
/*&nbsp;code&nbsp;one&nbsp;comments&nbsp;*/<br>
program&nbsp;code&nbsp;one<br>
/*&nbsp;code&nbsp;two&nbsp;comments&nbsp;*/<br>
program&nbsp;code&nbsp;two<br>
<br>
应如下书写<br>
/*&nbsp;code&nbsp;one&nbsp;comments&nbsp;*/<br>
program&nbsp;code&nbsp;one<br>
<br>
/*&nbsp;code&nbsp;two&nbsp;comments&nbsp;*/<br>
program&nbsp;code&nbsp;two<br>
&amp;sup1;&nbsp;2-14：对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。<br>
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。<br>
&amp;sup1;&nbsp;2-15：对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。<br>
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。<br>
示例（注意斜体加粗部分）：<br>
case&nbsp;CMD_UP:&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessUp();&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;break;<br>
<br>
case&nbsp;CMD_DOWN:&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessDown();&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;break;<br>
<br>
case&nbsp;CMD_FWD:&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessFwd();&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<br>
if&nbsp;(...)<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;...<br>
&nbsp;&nbsp;&nbsp;&nbsp;break;<br>
}<br>
else<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessCFW_B();&nbsp;&nbsp;&nbsp;//&nbsp;now&nbsp;jump&nbsp;into&nbsp;case&nbsp;CMD_A<br>
}<br>
<br>
case&nbsp;CMD_A:&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessA();&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;break;<br>
<br>
case&nbsp;CMD_B:&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessB();&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;break;<br>
<br>
case&nbsp;CMD_C:&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessC();&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;break;<br>
<br>
case&nbsp;CMD_D:&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProcessD();&nbsp;&nbsp;&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;break;<br>
...<br>
&amp;frac12;&nbsp;2-1：避免在一行代码或表达式的中间插入注释。<br>
说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。<br>
&amp;frac12;&nbsp;2-2：通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。<br>
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。<br>
&amp;frac12;&nbsp;2-3：在代码的功能、意图层次上进行注释，提供有用、额外的信息。<br>
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。<br>
示例：如下注释意义不大。<br>
/*&nbsp;if&nbsp;receive_flag&nbsp;is&nbsp;TRUE&nbsp;*/<br>
if&nbsp;(receive_flag)<br>
<br>
而如下的注释则给出了额外有用的信息。&nbsp;<br>
/*&nbsp;if&nbsp;mtp&nbsp;receive&nbsp;a&nbsp;message&nbsp;from&nbsp;links&nbsp;*/<br>
if&nbsp;(receive_flag)<br>
&amp;frac12;&nbsp;2-4：在程序块的结束行右方加注释标记，以表明某程序块的结束。<br>
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。<br>
示例：参见如下例子。<br>
if&nbsp;(...)<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;program&nbsp;code<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;while&nbsp;(index&nbsp;&lt;&nbsp;MAX_INDEX)<br>
&nbsp;&nbsp;&nbsp;&nbsp;{<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;program&nbsp;code<br>
&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;/*&nbsp;end&nbsp;of&nbsp;while&nbsp;(index&nbsp;&lt;&nbsp;MAX_INDEX)&nbsp;*/&nbsp;//&nbsp;指明该条while语句结束<br>
}&nbsp;/*&nbsp;end&nbsp;of&nbsp;&nbsp;if&nbsp;(...)*/&nbsp;//&nbsp;指明是哪条if语句结束<br>
&amp;frac12;&nbsp;2-5：注释格式尽量统一，建议使用“/*&nbsp;……&nbsp;*/”。<br>
&amp;frac12;&nbsp;2-6：注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。<br>
说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。<br>
</td> 
          </tr>
          <tr>
            <td width="600"></td> 
          </tr>
		  <tr>
            <td width="600"><b>郑重声明</b><br>
              &nbsp;&nbsp; 近年来我站数百篇“原创文章”被一些媒体肆意转载，不但不标明出自“中国电子技术信息网”，而且把相关字眼删除！这是无视技术价值的盗窃行为，是对技术人员辛勤劳动的蔑视，我对此种行为表示强烈的谴责。<br>
              &nbsp;&nbsp; “本是同根生，相煎何太急”，考虑到我们做技术的都是同门兄弟，对以前的盗窃行为不再追究，今后再有此类事件，最低处理限度是“明示于天下”。在这里向转载过又标注了出处的兄弟媒体表示崇高的敬意！<br>
              &nbsp;&nbsp; 兄弟网站如果引用本站“原创文章”，请首先经本人许可，并标注“www.cetinet.com”或“中国电子技术信息网”字样。<br>
              &nbsp;&nbsp; 欢迎个人下载使用！</td> 
          </tr>
        </table>
      </td>
    </tr>
  </table>
  <br>
  <br>
</div>

</body>
<body bgcolor="#FFFFFF" text="#000000">
  <p align="center">
  本站所载文章力求原创，部分资料转自网上，假如您认为某些文章侵犯了您的权益，<br>
  请告知我们，我们将在最短的时间内删除有关文章。本站转载文章均注明出处。<br>
  兄弟网站如果转载本站文章请注明本站版权，谢谢！
  <p align="center">中国电子技术信息网 文章管理系统由：Aoe 制作<br>      
  Copyright (C) 2001-2004 CETINet.COM All Rights Reserved      
</body>    

</html>