快速业务通道

关于编程风格的讨论3

作者 佚名技术 来源 程序设计 浏览 发布时间 2012-06-29

三、注释规范:

1、函数头的注释

对于函数,应该从“功能”,“参数”,“返回值”、“主要思路”、“调用方法”、“日期”六个方面用如下格式注释:

//程序说明开始

//================================================================//

// 功能: 从一个String 中删除另一个String。

// 参数: strByDelete,strToDelete

// (入口) strByDelete: 被删除的字符串(原来的字符串)

// (出口) strToDelete: 要从上个字符串中删除的字符串。

// 返回: 找到并删除返回1,否则返回0。(对返回值有错误编码的要// 求列出错误编码)。

// 主要思路:本算法主要采用循环比较的方法来从strByDelete中找到

// 与strToDelete相匹配的字符串,对多匹配strByDelete

// 中有多个strToDelete子串)的情况没有处理。请参阅:

// 书名......

// 调用方法:......

// 日期:起始日期,如:2000/8/21.9:40--2000/8/23.21:45

//================================================================//

函数名(……)

//程序说明结束

①、对于某些函数,其部分参数为传入值,而部分参数为传出值,所以对参数要详细说明该参数是入口参数,还是出口参数,对于某些意义不明确的参数还要做详细说明(例如:以角度作为参数时,要说明该角度参数是以弧度(PI),还是以度为单位),对既是入口又是出口的变量应该在入口和出口处同时标明。等等。

②、函数的注释应该放置在函数的头文件中,在实现文件中的该函数的实现部分应该同时放置该注释。

③、在注释中应该详细说明函数的主要实现思路、特别要注明自己的一些想法,如果有必要则应该写明对想法产生的来由。对一些模仿的函数应该注释上函数的出处。

④、在注释中详细注明函数的适当调用方法,对于返回值的处理方法等。在注释中要强调调用时的危险方面,可能出错的地方。

⑤、对日期的注释要求记录从开始写函数到结束函数的测试之间的日期。

⑥、对函数注释开始到函数命名之间应该有一组用来标识的特殊字符串。

如果算法比较复杂,或算法中的变量定义与位置有关,则要求对变量的定义进行图解。对难以理解的算法能图解尽量图解。

2、变量的注释:

对于变量的注释紧跟在变量的后面说明变量的作用。原则上对于每个变量应该注释,但对于意义非常明显的变量,如:i,j等循环变量可以不注释。

例如: long lLineCount //线的根数。

3、文件的注释:

文件应该在文件开头加入以下注释:

/////////////////////////////////////////////////////////////////////

// 工程: 文件所在的项目名。

// 作者:**,修改者:**

// 描述:说明文件的功能。

// 主要函数:…………

// 版本: 说明文件的版本,完成日期。

// 修改: 说明对文件的修改内容、修改原因以及修改日期。

// 参考文献: ......

/////////////////////////////////////////////////////////////////////

为了头文件被重复包含要求对头文件进行定义如下:

#ifndef __FILENAME_H__

#define __FILENAME_H__

其中FILENAME为头文件的名字。

4、其他注释:

在函数内我们不需要注释每一行语句。但必须在各功能模块的每一主要部分之前添加块注释,注释每一组语句,在循环、流程的各分支等,尽可能多加以注释。

其中的循环、条件、选择等位置必须注释。

对于前后顺序不能颠倒的情况,建议在注释中增加序号。

例如:

......
//1、......注释
for (......)
{
}
if(......)
{//......注释
}
else
{//......注释
}
//......注释
switch(......)
{
case: ......// ......注释
......
case: ......// ......注释
......
default: //......注释
......
}

在其他顺序执行的程序中,每隔3-5行语句,必须加一个注释,注明这一段语句所组成的小模块的作用。对于自己的一些比较独特的思想要求在注释中标明。

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务,公司网站:http://www.lingzhong.cn 为了给广大客户了解更多的技术信息,本技术文章收集来源于网络,凌众科技尊重文章作者的版权,如果有涉及你的版权有必要删除你的文章,请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息,谢谢!

分享到: 更多

Copyright ©1999-2011 厦门凌众科技有限公司 厦门优通互联科技开发有限公司 All rights reserved

地址(ADD):厦门软件园二期望海路63号701E(东南融通旁) 邮编(ZIP):361008

电话:0592-5908028 传真:0592-5908039 咨询信箱:web@lingzhong.cn 咨询OICQ:173723134

《中华人民共和国增值电信业务经营许可证》闽B2-20100024  ICP备案:闽ICP备05037997号