程序代码注释编写规范

第一篇：程序代码注释编写规范

程序代码注释编写规范

为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。一般情况下，源程序有效注释量必须在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: Version : Date: DESCRIPTION: // 模块描述，描述本文件的内容、功能、内部各部分之间的关系及

//本文件与其它文件关系等 Version:

// 版本信息

Function List:

// 主要函数及其功能 1.-------History:

// 历史修改记录

**********************************************************/

三、函数

函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。

示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

/************************************************* Function:

// 函数名称

DESCRIPTION: // 函数功能、性能等的描述 Calls:

// 被本函数调用的函数清单 Called By:

// 调用本函数的函数清单

Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）Table Updated: // 被修改的表（此项仅对于牵扯到数据库操作的程序）Input:

// 输入参数说明，包括每个参数的作

// 用、取值说明及参数间关系。OUTPUT:

// 对输出参数的说明。Return:

// 函数返回值的说明 Others:

// 其它说明

*************************************************/

四、变量寄存器

标志变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。示例：

Unsigned char receive_floag;//接收标志；

/* 0—接收失败, 1—接收成功, 2—…….*/

/*

receive _process()

*/

//调用函数

Unsigned char receive_data[10];//数据接收存储器；

/*在 receive _bit()中对其赋值*/

//调用函数

五、控制寄存器

在对控制器控制寄存器进行操作时，需注明该寄存器功能，配置参数作用，以及配置时的注意事项等的说明。示例：（PIC单片机定时器控制）void time0_init(void){ T0CON=0X09;

//设定TMR0工作于16位定时器方式,内部时钟,不分频 INTCON=INTCON|0X20;//TMR0中断允许

INTCON=INTCON&0Xfb;//清除TMR0的中断标志

INTCON=INTCON|0xc0;//* 开总中断、开外围接口中断

TMR0H= 0xaa;

TMR0L= 0xaa;}

// 对TMR0写入初值.注意:与溢出中断写初值不同

第二篇：C语言 程序代码编写规范

C语言 程序代码编写规范

（初级程序员 讨论版）

前言

一个好的程序编写规范是编写高质量程序的保证。清晰、规范的源程序不仅仅是方便阅读，更重要的是能够便于检查错误，提高调试效率，从而最终保证软件的质量和可维护性。

说明

此文挡还在完善改进中，如有不足，欢迎指正。本文档主要适用于刚刚开始接触编程的初学者。

对于具有一定工程项目开发经验的程序员，建议学习C语言程序代码编写规范—高级版。

目录 代码书写规范 2 注释书写规范 3 命名规范内容代码书写规范

1.1函数定义

每个函数的定义和说明应该从第1列开始书写。函数名（包括参数表）和函数体的花括号（“{”和“}”）应该各占一行。在函数体结尾的括号（“}”）后面应该加上注释，注释中应该包括函数名，这样比较方便进行括号配对检查，也可以清晰地看出来函数是否结束。

范例1：函数的声明

void matMyFunction(int n){ …… } /* matMyFunction*/ 1.2空格的使用

使用空格分割所有演算符号和操作数。

这条规则的例外是“->”,““.”, “()”和“[]”，这些操作符和操作数之间不空格。当需要把一个程序行的内容分成几行写时，操作符号应该放在行末，而不是下一行的开头。

1.3缩进的设置

代码书写应该遵从结构化的要求，采用缩进的格式。最小缩进量为4个空格，整个文件内部应该统一，不要混用Tab键和4个空格这两种情况，因为不同的编辑器对Tab键的处理方法不同。

1.4折行的使用

每行的长度不要超过80个字符，当程序行太长时，应该分行书写。分行时应该按照自然的逻辑关系进行，例如：不要把一个简单的逻辑判断写在两行上。

分行后的缩进应该按照程序的逻辑关系进行对齐。例如：参数表折行后，下面的行应该在参数表左括号的下方。

范例2：折行的格式dwNewShape = matAffineTransform(coords, translation，rotation);

if(((new_shape.x > left_border)&&

(new_shape.x < right_border))&&

((new_shape.y > bottom_border)&&

(new_shape.y < top_border))){

draw(new_shape);}

1.5嵌套语句（语句块）的格式

对于嵌套式的语句--即语句块（如，if、while、switch等）应该包括在花括号中。花括号的左括号应该单独占一行，并与关键字对齐。建议即使语句块中只有一条语句，也应该使用花括号包括，这样可以使程序结构更清晰，也可以避免出错。建议对比较长的块，在末尾的花括号后加上注释以表明该语言块结束。

范例3：嵌套语句格式 if(value < max){

if(value!= 0)

{

func(value);

} } } else {

error(“The value is too big.”);} /* if(value < max)*/ 注释书写规范

注释必须做到清晰，准确地描述内容。对于程序中复杂的部分必须有注释加以说明。注释量要适中，过多或过少都易导致阅读困难。

2.1注释风格

语言中使用一组（/* … */）作为注释界定符。注释内容尽量用英语方式表述。

注释的基本样式参考范例4。

注释应该出现在要说明的内容之前，而不应该出现在其后。

除了说明变量的用途和语言块末尾使用的注释，尽量不使用行末的注释方式。

范例4：几种注释样式

/*

* ************************************************* 强调注释

* ************************************************ */ /* * 块注释 */

/* 单行注释 */

int i;/*行末注释*/ 2.2何时需要注释

如果变量的名字不能完全说明其用途，应该使用注释加以说明。

如果为了提高性能而使某些代码变得难懂，应该使用注释加以说明。对于一个比较长的程序段落，应该加注释予以说明。如果设计文档中有流程图，则程序中对应的位置应该加注释予以说明。

如果程序中使用了某个复杂的算法，建议注明其出处。

如果在调试中发现某段落容易出现错误，应该注明。命名规范

3.1常量、变量命名

用#define定义的符号常量全部采用大写。

变量命名的基本原则：

可以选择有意义的英文（小写字母）组成变量名，使人看到该变量就能大致清 楚其含义。

不要使用人名、地名和汉语拼音。

如果使用缩写，应该使用那些约定俗成的，而不是自己编造的。

多个单词组成的变量名，每个单词的首字母应该大写。如：dwUserInputValue。

3.2函数命名

函数命名原则与变量命名原则基本相同。对于初学者，函数命名可以采用 “FunctionName”的形式。

第三篇：学术论文注释规范

学术论文注释规范

一、文后参考文献及其随文夹注格式

参考文献按在正文中出现的先后次序列于文末，以“参考文献：”（左顶格）作为标识。参考文献的序号左顶格，并用数字加方括号表示，如[1]，[2]，…；每一条参考文献条目的最后均以小圆点“.”结束。

引文的起止页码以随文以夹注的形式、用6号宋体标出，其格式为：[序号]（p×）。

各类参考文献及其在正文中夹注的格式及示例如下：

（一）专著、论文集、学位论文、报告

[序号]主要责任者.文献题名[文献类型标识].出版地：出版者，出版年.[1] 列维·布留尔.原始思维[M].北京：商务印书馆，1987.[2] 马克思.恩格斯.共产党宣言[A].马克思恩格斯选集[M].第一卷.北京：人民出版社，1972.[3] 洪亮吉.春秋左传诂[M].卷三.[4] 人事部一·叙人[A].太平御览[M].北京：中华书局，1960.[5] 皇甫湜.皇甫持正文集[M].卷四.四部丛刊本.[6] 房玄龄等.晋书·司马彪传[M].北京：中华书局，1974.[7] Chester.The Rise of British Industrial Society[M].Longman, 1982.以例[6]、[7]为例，其随文夹注格式分别为： [6]（p.4142.）、[7]（p.289.）。

多次引用同一本书中的材料，随文夹注中一律采用第一次出现的序号。例如：第一次引用[7]中材料时，夹注为“[7]（p289）”；第二次引用[7]中材料时，夹注为“[7]（p163）”。多种材料说明一个问题，在随文夹注中则按次序列出，例：“[4]（p×）；[5]（p×）”。

（二）期刊文章

[序号]主要责任者.文献题名[J].刊名，年，卷（期）.例：

[8] 李醒民.哲学不是敲门砖和摇钱树[J].学术界，2000，（1）.随文夹注格式： [8]（p206）。

（三）论文集中的析出文献

[序号]析出文献主要责任者.析出文献题名[A].原文献主要责任者（任选）.原文献题名[C].出版地：出版者，出版年.例：

[9] 王旭.美国三大城市与美国现代区域经济结构[A].中国美国史研究学会.美国现代化历史经验[C].北京：东方出版社，1994.随文夹注格式：[9]（p183）。

（四）报纸文章

[序号]主要责任者.文献题名[N].报纸名，出版日期（版次）.例：

[10]杨玉圣.把书评当作学问来做[N].中华读书报，1996-10-09（2）.（五）电子文献

[序号]主要责任者.电子文献题名[电子文献及载体类型标识].电子文献的出处或可获得地址，发表或更新日期/引用日期.例：

[11]王明亮.关于中国学术期刊标准化数据库系统工程的进展[EB/CD].http://,1998-08-16/1998-10-04.报纸文章和电子文献在随文夹注中直接以序号标出，而省略“（p×）”著录项。

（六）各种未定义类型的文献

[序号]主要责任者.文献题名[Z].出版地：出版者，出版年.例：

[12]何晓明.降落民间——21世纪中国历史学走向管窥（第十一届全国史学理论研讨会论文）[Z].武汉：湖北大学中国文化研究院，2000.二、参考文献与注释的区别

参考文献是作者写作论著时所参考的文献书目，集中列于文末；注释则是作者对论著正文中某一特定内容的进一步解释或补充说明，列于该页地脚（以脚注形式标出）。参考文献序号用方括号标注，注释序号则用数字加圆圈标注，位于标点符号之后；若是直接引文，则位于后引号之后。

附1：参考文献类型及其标识

参考文献 专著 论文集 析出文献 报纸文章 期刊文章 学位论文 报 告

文献类型标识 M C A N J D R 无法根据上述分类的文献，其标识码一律用“Z”表示。

附2：电子文献的载体类型及其标识（[文献类型标识/载体类型标识]）

电子文献载体类型：磁带（magnetic tape）——MT；磁盘（disk）——DK；光盘（CD-ROM）——CD；联机网络（online）——OL。按下列格式表示包括了文献载体类型的参考文献类型标识：

[DB/OL]——联机网上数据库（database online）

[DB/MT]——磁带数据库（database on magnetic tape）

[M/CD]——光盘图书（monograph on CD-ROM）

[CP/DK]——磁盘软件（computer program on disk）

[J/OL]——网上期刊（serial online）

[EB/OL]——网上电子公告（electronic bulletin online）

第四篇：参考文献及注释规范

一、基本概念

（1）“注释”指作者进一步解释自己所要表达的意思，注释安排在当页页脚，用带圈数字表示序号，如注①、注②等，注释的序号与文中序号一一对应。

（2）“参考文献”指作者引文所注的出处，一律放在论文尾末，文中设序号 [1]，参考文献的序号与文中序号一一对应。页码置于文中序号之后，例： [1]（P12）。

（3）“参考文献”也指虽未直接引述别人的话、但参考了别人著作和论文的意思，应在段中或段末设序号 [1]，并在文末注明。本项与第2项不必分列，交叉排序即可。文末的序号与文中序号一一对应。此种情况可以不注明页码。

（4）同一参考文献多次被引用，文末只标一个序号，文中应多次出现同一序号，在文中序号后加圆括号，注明所引文献的不同页码或篇名。

（5）参考文献与注释的区别。参考文献是作者写作论著时所参考的文献书目，集中列于文末；注释则是作者对论著正文中某一特定内容的进一步解释或补充说明，列于该页地脚（以脚注形式标出）。参考文献序号用方括号标注，注释序号则用数字加圆圈标注，位于标点符号之后；若是直接引文，则位于后引号之后。

二、中文参考文献及注释规范

（一）、文后参考文献及其随文夹注格式

参考文献按在正文中出现的先后次序列于文末，以“参考文献：”（左顶格）作为标识。参考文献的序号左顶格，并用数字加方括号表示，如[1]，[2]，…；每一条参考文献条目的最后均以小圆点“.”结束。

引文的起止页码以随文以夹注的形式、用6号宋体标出，其格式为：[序号]（p×）。各类参考文献及其在正文中夹注的格式及示例如下：

1、专著、论文集、学位论文、报告

[序号]主要责任者.文献题名[文献类型标识].出版地：出版者，出版年.[1] 列维·布留尔.原始思维[M].北京：商务印书馆，1987.[2] 马克思.恩格斯.共产党宣言[A].马克思恩格斯选集[M].第一卷.北京：人民出版社，1972.[3] 洪亮吉.春秋左传诂[M].卷三.[4] 人事部一·叙人[A].太平御览[M].北京：中华书局，1960.[5] 皇甫湜.皇甫持正文集[M].卷四.四部丛刊本.[6] 房玄龄等.晋书·司马彪传[M].北京：中华书局，1974.[7] Chester.The Rise of British Industrial Society[M].Longman, 1982.以例[6]、[7]为例，其随文夹注格式分别为： [6]（p.4142.）、[7]（p.289.）。

多次引用同一本书中的材料，随文夹注中一律采用第一次出现的序号。例如：第一次引用[7]中材料时，夹注为“[7]（p289）”；第二次引用[7]中材料时，夹注为“[7]（p163）”。多种材料说明一个问题，在随文夹注中则按次序列出，例：“[4]（p×）；[5]（p×）”。

2、期刊文章

[序号]主要责任者.文献题名[J].刊名，年，卷（期）.例：

[8] 李醒民.哲学不是敲门砖和摇钱树[J].学术界，2000，（1）.随文夹注格式： [8]（p206）。

3、论文集中的析出文献

[序号]析出文献主要责任者.析出文献题名[A].原文献主要责任者（任选）.原文献题名[C].出版地：出版者，出版年.例：

[9] 王旭.美国三大城市与美国现代区域经济结构[A].中国美国史研究学会.美国现代化历史经验[C].北京：东方出版社，1994.随文夹注格式：[9]（p183）。

4、报纸文章

[序号]主要责任者.文献题名[N].报纸名，出版日期（版次）.例：

[10]杨玉圣.把书评当作学问来做[N].中华读书报，1996-10-09（2）.5、电子文献

[序号]主要责任者.电子文献题名[电子文献及载体类型标识].电子文献的出处或可获得地址，发表或更新日期/引用日期.例：

[11]王明亮.关于中国学术期刊标准化数据库系统工程的进展[EB/CD].http://,1998-08-16/1998-10-04.报纸文章和电子文献在随文夹注中直接以序号标出，而省略“（p×）”著录项。

6、各种未定义类型的文献 [序号]主要责任者.文献题名[Z].出版地：出版者，出版年.例：

[12]何晓明.降落民间——21世纪中国历史学走向管窥（第十一届全国史学理论研讨会论文）[Z].武汉：湖北大学中国文化研究院，2000.三、英文参考文献及注释规范

英文参考文献Bibliography（Bibliography使用“Times New Roman”字体，小四号，加粗，后面不加任何标点符号。）

1.专著：

1)基本格式（请严格注意标点符号）：作者的姓名（英文作者的姓，名）.年份.书名（斜体）.出版地:出版商.如果同一作者两本以上同年出版的参考书，在年份后用a，b，c 等标出； 如有第二行，则须缩进4个英文字符。例：

Chomsky, N.1981a.Lectures on government and binding.Dordrecht: Foris.Chomsky, N.1981b.Theory of markedness in generative grammar.Pisa, Italy: Scuola Normale Superiore.2)书的主编（格式：各项信息的排列顺序基本同上，在主编姓名后加ed.）：

例：Hall, David, ed.1981.The Oxford book of American literary anecdotes.New York: OUP.3)机构作者（格式：各项信息的排列顺序基本同上）：

例：American library association.1983.Intellectual freedom manual.2nd ed.Chicago: ALA.4)翻译著作（格式：各项信息的排列顺序基本同上，加xx Trans.）：

例：Calvino, Ian.1986.The uses of literature.P.Creagh Trans.San Diego: Harcourt.2.文章：

1)期刊文章基本格式（请严格注意标点符号）：作者姓名.年份.篇名.刊名（要斜体）.刊物的卷号和期号:文章的起止页码.例：

Boling, D.1965.The atomization of meaning.Language 41:555-573.2)论文集中的文章基本格式（请严格注意标点符号）：作者姓名.年份.篇名.论文集作者姓名.eds.论文集名称（要斜体）.出版地:出版商.文章的起止页码.例：

Peters, M & T.B.Stephen.1986.Interaction routines as cultural influences upon language acquisition.In Schieffelin, B.B.& E.Ochs, eds.Language Socialization Across Cultures.Cambridge: CUP, 80-96.附1：参考文献类型及其标识

参考文献 专著 论文集 析出文献 报纸文章 期刊文章 学位论文 报告

文献类型标识 M C A N J D R 无法根据上述分类的文献，其标识码一律用“Z”表示。

附2：电子文献的载体类型及其标识（[文献类型标识/载体类型标识]）

电子文献载体类型：磁带（magnetic tape）——MT；磁盘（disk）——DK；光盘（CD-ROM）——CD；联机网络（online）——OL。按下列格式表示包括了文献载体类型的参考文献类型标识：

[DB/OL]——联机网上数据库（database online）

[DB/MT]——磁带数据库（database on magnetic tape）

[M/CD]——光盘图书（monograph on CD-ROM）

[CP/DK]——磁盘软件（computer program on disk）

[J/OL]——网上期刊（serial online）

[EB/OL]——网上电子公告（electronic bulletin online）

第五篇：C# 注释规范

C# 注释（Comment）规范

注释规范包括：模块（类）注释规范、类的属性、方法注释规范、代码间注释

1.模块（类）注释规范

模块开始必须以以下形式书写模块注释：

///

///

2.类属性注释规范

在类的属性必须以以下格式编写属性注释：

///

3.方法注释规范

在类的方法声明前必须以以下格式编写注释

///

"><参数说明> /// ///<对方法返回值的说明，该说明必须明确说明返回的值代表什么含义> ///

4.代码间注释规范

代码间注释分为单行注释和多行注释：

单行注释： //<单行注释>

多行注释： /*多行注释1 多行注释2 多行注释3*/

代码中遇到语句块时必须添加注释（if,for,foreach,……）,添加的注释必须能够说明此语句块的作用和实现手段（所用算法等等）。

详细介绍见：

http://