代码注释规范说明

合集下载

Python代码注释规范

Python代码注释规范Python代码注释规范是一种良好的编程习惯，能够为团队协作和代码维护带来便利。

本论文对Python注释规范进行了详细阐述，主要内容包括注释的类型、注释的位置与方式、注释内容等。

一、注释的类型Python代码中的注释主要包括两种：单行注释和多行注释。

单行注释以“#”开头，多行注释以“'''”或“"""”包裹。

1.单行注释单行注释适用于注释单行代码以及在代码之后加上注释。

注释一般写在代码上方，或者代码语句结束后的行首。

可以对Python代码进行单行注释。

这类注释是使用最为广泛的注释类型。

例如：```#这是一条单行注释print("Hello World") #这也是一条单行注释```2.多行注释多行注释在不同场合都有用处，如当需要注释一整段代码时，或者需要多次添加注释时。

这类注释使用三个引号包裹起来的多行字符串形式。

例如：```"""这是一条多行注释多行注释适用于注释多行代码"""print("Hello World")```二、注释的位置与方式Python代码中注释的写法和位置选择非常重要。

注释应当在语句上方，而不是在语句的行末。

这样可以更好地防止注释失效，使代码更易于阅读和维护。

1.单行注释的位置单行注释应放在被注释语句的上方，或者被注释语句的结束行。

如果注释与被注释语句在同一行，注释符“#”和代码之间应该保留一个空格。

如果注释与被注释语句在不同行，注释应该紧跟在代码后面，并且注释与代码应该在同一缩进级别。

例如：```#这是单行注释，最好与代码之间留一个空格print("Hello World") #这也是单行注释x = 5 #多行语句的注释同样适用于单行语句的注释#这是一个单行注释#这是一个单行注释```2.多行注释的位置多行注释可以写在程序外面，也可以写在函数、方法、类等数据对象内部。

程序源代码注释规范

程序注释规范说明程序注释规范应包括以下三方面：一、文件头部注释在代码文件的头部进行注释，这样做的好处在于，我们能对代码文件做变更跟踪。

在代码头部分标注出创始人、创始时间、修改人、修改时间、代码的功能，这在团队开发中必不可少，它们可以使后来维护/修改的同伴在遇到问题时，在第一时间知道他应该向谁去寻求帮助，并且知道这个文件经历了多少次迭代、经历了多少个程序员的开发和修改。

样本：/***************************************************** ** 作者：Liuchao** 创始时间：2007-11-12** 修改人：Liuchao** 修改时间：2007-11-12** 修改人：Liaochao** 修改时间：2007-11-12** 描述：** 主要用于产品信息的资料录入，…*****************************************************/二、函数、属性、类等注释请使用///三斜线注释，这种注释是基于XML的，不仅能导出XML制作帮助文档，而且在各个函数、属性、类等的使用中，编辑环境会自动带出注释，方便你的开发。

以protected，protected Internal，public声明的定义注释都建议以这样命名方法。

例如：/// <summary>/// 用于从ERP系统中捞出产品信息的类/// </summary>class ProductTypeCollector{…}三、逻辑点注释在我们认为逻辑性较强的地方加入注释，说明这段程序的逻辑是怎样的，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG。

在注释中写明我们的逻辑思想，对照程序，判断程序是否符合我们的初衷，如果不是，则我们应该仔细思考耀修改的是注释还是程序了…四、变量注释我们在认为重要的变量后加以注释，说明变量的含义，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG.我们常用///三斜线注释。

python注释规范

python注释规范Python注释规范编写清晰、易读和可维护的代码是每个开发者的目标。

良好的代码注释是实现这一目标的关键之一。

本文将介绍Python中的注释规范，帮助开发者编写更好的代码。

1. 注释的作用注释是一种用于解释代码的文本，它不会被解释器执行。

注释的作用是提高代码的可读性，方便其他人理解代码的含义，也便于自己回顾和修改代码。

2. 单行注释单行注释用于解释单行代码的含义或提醒某些特殊情况。

在Python中，单行注释以井号（#）开头。

示例：```python# 计算两个数的和sum = a + b```3. 多行注释多行注释用于解释一段代码的含义或提供更详细的文档说明。

在Python中，多行注释使用三个引号（'''）或三个双引号（"""）包围。

示例：```python'''这是一个多行注释可以用于提供更详细的代码说明'''```4. 函数注释函数注释用于解释函数的参数、返回值和功能。

在Python中，函数注释使用函数的定义行下面的一行进行注释。

注释内容应包含函数的参数和返回值的类型、功能的描述以及可能的异常情况。

示例：```pythondef add(a: int, b: int) -> int:'''计算两个数的和参数:- a: 第一个数- b: 第二个数返回值:- 两个数的和异常:- 如果参数不为整数类型，将抛出TypeError异常'''return a + b```5. 类注释类注释用于解释类的作用和功能。

在Python中，类注释和函数注释类似，可以在类的定义行下面的一行进行注释。

注释内容应包含类的作用和功能的描述。

示例：```pythonclass Calculator:'''计算器类特点:- 支持加法、减法、乘法和除法运算- 可以处理整数和浮点数用法:calculator = Calculator()result = calculator.add(2, 3)'''def add(self, a, b):return a + b```6. 模块注释模块注释用于解释整个模块的功能和用途。

程序注释规范

程序注释规范程序注释是程序中用来解释代码逻辑、功能和设计意图的文本，它可以提高代码的可读性和可维护性，方便他人理解和修改代码。

下面是程序注释的一些规范和最佳实践，旨在帮助开发人员编写清晰、明确和易于理解的注释。

1. 注释格式* 使用自然语言编写注释，要求语法清晰、无歧义，避免使用缩写词和专业术语，尽量使用简单明了的表达方式。

* 注释应该和代码保持一致的缩进和对齐，便于阅读和理解。

* 建议使用统一的注释格式，例如Javadoc风格的注释`/** ... */`，或者Python风格的注释`""" ... """`。

* 将注释与代码之间使用空行分隔，提高可读性。

* 在每个类或函数的开头，应该描述其功能和使用方法，以及参数和返回值的说明。

* 在复杂的代码段或算法的开头，应该提供整体思路的注释，以便理解其设计意图。

* 对于关键的变量和数据结构，应该解释其用途、取值范围和可能的副作用。

* 对于代码中的难以理解的逻辑或复杂的算法，应该给出详细的注释，解释其意义和实现方法。

* 对于临时的代码或待修改的代码段，应该标注TODO或FIXME，提示后续开发人员需要注意的问题。

* 避免写无意义或重复的注释，如将代码直接复制到注释中，或使用无关的词语描述代码。

* 调试代码时添加的注释，在提交代码前应该删除或注释掉，以免影响代码的可读性。

3. 注释语法* 对于函数和方法，使用合适的语法描述其参数和返回值。

例如，使用`@param`注释描述参数，使用`@return`注释描述返回值。

* 对于循环和条件语句，注释应该解释其目的和条件，以及可能的结果和副作用。

* 对于变量和常量，注释应该描述其用途、取值范围和可能的副作用。

* 在代码的重要部分和关键路径前后追加注释，以便于快速定位和理解核心逻辑。

Python代码规范（命名、注释等）

Python代码规范（命名、注释等）本来不应该把这个章节放在前⾯的，因为还没进⾏学习之前，直接看这个章节，会感觉有很多莫名其妙的东西。

但是把这个章节放在前⾯的⽤意，只是让⼤家预览⼀下，有个印象，⽽且在以后的学习中，也⽅便⼤家查阅。

⽬录⼀、简明概述1、编码如⽆特殊情况, ⽂件⼀律使⽤ UTF-8 编码如⽆特殊情况, ⽂件头部必须加⼊#-*-coding:utf-8-*-标识2、代码格式2.1、缩进统⼀使⽤ 4 个空格进⾏缩进2.2、⾏宽每⾏代码尽量不超过 80 个字符(在特殊情况下可以略微超过 80 ，但最长不得超过 120)理由：这在查看 side-by-side 的 diff 时很有帮助⽅便在控制台下查看代码太长可能是设计有缺陷2.3、引号单引号简单说，⾃然语⾔使⽤双引号，机器标⽰使⽤单引号，因此代码⾥多数应该使⽤代码⾥多数应该使⽤单引号使⽤双引号'...'⾃然语⾔⾃然语⾔使⽤双引号例如错误信息；很多情况还是 unicode，使⽤u'你好世界'使⽤单引号'...'例如 dict ⾥的 key机器标识使⽤单引号机器标识使⽤原⽣的双引号r'...'正则表达式使⽤原⽣的双引号正则表达式⽂档字符串 (docstring)使⽤三个双引号'''......'''2.4、空⾏模块级函数和类定义之间空两⾏；类成员函数之间空⼀⾏；可以使⽤多个空⾏分隔多组相关的函数函数中可以使⽤空⾏分隔出逻辑相关的代码3、import 语句import 语句应该分⾏书写# 正确的写法import osimport sys# 不推荐的写法import sys,os# 正确的写法from subprocess import Popen, PIPEimport语句应该使⽤absoluteimport# 正确的写法from foo.bar import Bar# 不推荐的写法from ..bar import Barimport语句应该放在⽂件头部，置于模块说明及docstring之后，于全局变量之前；import语句应该按照顺序排列，每组之间⽤⼀个空⾏分隔导⼊其他模块的类定义时，可以使⽤相对导⼊from myclass import MyClass如果发⽣命名冲突，则可使⽤命名空间4、空格在⼆元运算符两边各空⼀格[=,-,+=,==,>,in,is not, and]:函数的参数列表中，,之后要有空格函数的参数列表中，默认值等号两边不要添加空格左括号之后，右括号之前不要加多余的空格5、换⾏Python ⽀持括号内的换⾏。

js注释规范

js注释规范JavaScript注释规范注释是程序代码中的重要组成部分，它有助于代码的可读性和可维护性。

在JavaScript中，注释以"//"或者"/*...*/"的形式存在。

为了提高代码的可读性，以下是JavaScript注释的一些常见规范：1. 单行注释单行注释通常用于解释代码的目的或者作用。

在注释之前使用两个斜杠"//"，并在注释内容和斜杠之间留一个空格。

比如：```// 这是一个单行注释```2. 多行注释多行注释通常用于解释较长的代码块或者注释大段的文字。

在多行注释的前后使用"/*"和"*/"，比如：```/*这是一个多行注释可以跨越多行*/```3. 函数注释函数注释通常在函数的声明之前进行，用于解释函数的功能、参数、返回值等相关信息。

通常以斜杠和两个星号开头，然后依次注释参数和返回值。

例如：```/*** 计算两个数的和* @param {number} a 第一个数* @param {number} b 第二个数* @returns {number} 两个数的和*/function add(a, b) {return a + b;}```在函数注释中，使用@符号来标记特殊的注释块，如@param 表示参数，@returns表示返回值。

4. 类注释类注释用于解释类的功能、属性和方法等信息。

通常在类的声明之前进行，使用与函数注释类似的方式。

例如：```/*** 表示一个人的类* @class*/class Person {/*** 创建一个人的实例* @constructor* @param {string} name - 姓名* @param {number} age - 年龄*/constructor(name, age) { = name;this.age = age;}/*** 获取人的姓名* @returns {string} 姓名*/getName() {return ;}}```5. 变量注释变量注释用于解释变量的用途、类型和可能的取值范围等信息。

程序代码注释编写规范

程序代码注释编写规范为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。

一般情况下,源程序有效注释量必须在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。

＊*＊＊＊**＊＊*＊**＊**＊＊＊＊＊＊*＊＊**＊*＊*＊＊＊＊＊****＊＊＊＊＊＊＊＊＊/二、源文件头源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。

python的注释规则

python的注释规则Python的注释规则非常重要，它们可以增加代码的可读性，并帮助他人理解你的代码。

在编写注释时，有一些规则和惯例被广泛遵循，这些规则可以提高代码的可维护性和可理解性。

以下是Python中常见的注释规则：1. 单行注释：使用 # 符号来添加单行注释。

单行注释通常用于在特定行上解释代码的含义或目的。

注释应该直接跟随在要解释的代码行的后面，并以一个空格分隔。

例如：```python# 这是一个简单的加法函数def add(a, b):return a + b```2. 多行注释：使用三引号（''' 或 """）来添加多行注释。

多行注释通常用于解释函数、类或模块的功能，以及为模块提供全局描述。

在多行注释中，通常使用一段话或若干句子来描述代码的用途和实现逻辑。

例如：```python'''这是一个用于计算圆的面积和周长的函数。

它接受一个半径作为参数，并返回面积和周长的值。

'''def calculate_circle(radius):# 计算面积area = 3.14 * radius * radius# 计算周长perimeter = 2 * 3.14 * radiusreturn area, perimeter```3. 注释风格：注释应该简洁明了，使用正确的语法和标点符号。

首字母大写、句子结束使用句点、使用正确的单复数形式等等。

注释的目的是帮助他人理解和使用你的代码，因此要尽量避免使用缩写、俚语或不确定的语言。

例如：```python# 这个函数用于从列表中删除重复的元素。

def remove_duplicates(lst):# 创建一个空集合用于存储唯一的元素。

unique_elements = set()for element in lst:# 将元素添加到集合中，如果元素已经存在则不会重复添加。

1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。

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: 英文<Modify>缩写
060806：代表修改日期为2006.08.06
A：代表当天添加或者修改的第一项功能。

如果当日继续做其他有别与本次功能差异的修改，可以采用M060806_B的方法，依次类推（A、B、C、D、E、F……） .
3．《PROJECT》：主要描述当前代码的修改所针对的项目，由于以后的多个项目可能用一套代码通过宏来定义，所以如果当前代码的修改是针对两个或两个以上的项目，我们这里使用COMMON加以区分。

4.《SUMMARY》：主要简述此次代码修改的目的或者解决某个BUG的方法。

******************************************************************************** 〈Sample-1〉：
//M060806_A start
/*Do Battery Voltage Measure*/
static BOOL g_batteryADC = FALSE;
static DWORD dwCyc = 0;
static DWORD dwCount = 0;
//M060806_A end
<Sample-2>：
//M060812_B start--Change the USB CHANGING conditions
/*if(gpioGetValue(g_pGPIOregs,80) == 0) // nCHG assert
{
if(dwVolt < g_pdd.voltMax + 10) {
g_sps.BatteryFlag = BATTERY_FLAG_CHARGING;
}
else {
g_sps.BatteryFlag = BATTERY_FLAG_HIGH;
}
goto done;dwPercent < 100
}*/
if((dwVolt < g_pdd.voltMax) && (gpioGetValue(g_pGPIOregs, 1) == 0))//Here we do not to judge the CHG_nCHG PIN.
{
g_sps.BatteryFlag = BATTERY_FLAG_CHARGING;
goto done;
}
//M060812_B end
如果在代码修改过程中由于需要定义新的变量，可以参照〈Sample-1〉的方法。

在修改代码段<Sample-2>的过程中，我们最好在修改代码段暂时保留注释掉的源代码，这样方便我们以后如果出现问题时对修改代码和旧代码的对比检查。

注释掉的源代码，在通过正式版本的测试验证无误后，相关人员可以删除针对这个问题的所有标志符和相关代码。

具体操作可以参照Sample Code<Bat_pdd.c>！
希望大家有更好的建议或者方法，提出来大家共同讨论制定这项代码规范！谢谢！
Author:lizhuangzhi Date:2006.08.25。