Python代码注释规范实例如何详细解析？

本文共计1164个文字，预计阅读时间需要5分钟。

一、代码注释介绍注释就是对代码进行解释和说明。注释不是代码的一部分，不会影响程序的执行。注释的目的是让代码更易于理解和维护。

二、注释的作用

1.解释代码：对代码的某些部分进行解释，让其他人（或未来的自己）更容易理解代码的含义。

2.说明目的：说明代码的用途、功能和预期效果。

3.提示信息：对一些可能容易出错或需要特别注意的地方进行提示。

4.提高代码可读性：让代码更加清晰、易懂。

三、编写注释的注意事项

1.注释要简洁明了，避免冗长。

2.注释要准确，不要误导读者。

3.注释要规范，遵循一定的格式。

4.注释要适时更新，与代码保持一致。

一、代码注释介绍

• 注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。
• 注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。
• 在有处理逻辑的代码中，源程序有效注释量必须在20％以上。
  

二、代码注释分类

行注释：在符号后那一行不会被编译（显示）

块注释：被块注释符号中间的部分不会被编译

三、python代码注释基础

Python中使用#表示单行注释。单行注释可以作为单独的一行放在被注释代码行之上，也可以放在语句或表达式之后。如下例子：

name = 'xiaohong' # 单行注释

# 单行注释
name = 'xiaohong'

Python中使用三个单引号或三个双引号表示多行注释。用在注释多写不下的情况，如下例子：

'''
这是使用三个单引号的多行注释
'''

"""
这是使用三个双引号的多行注释
"""

四、DocStrings介绍与使用

4.1 DocStrings介绍

文档字符串

是一个重要工具，用于解释文档程序，帮助你的程序文档更加简单易懂

4.2 python中使用DocStrings

在函数体的第一行使用一对三个单引号 ''' 或者一对三个双引号 """ 来定义文档字符串。你可以使用 doc（注意双下划线）调用函数中的文档字符串属性。

编写示例如下：

def add(num1,num2): """ 完成传入的两个数之和 :param num1: 加数1 :param num2: 加数2 :return: 和 """ return num1 + num2 print( add.__doc__ )

备注：DocStrings 文档字符串使用惯例：它的首行简述函数功能，第二行空行，第三行为函数的具体描述。

五、DocStrings常用编写风格

5.1 reST风格

这是现在流行的一种风格，reST风格，Sphinx的御用格式，比较紧凑。

""" This is a reST style. :param param1: this is a first param :param param2: this is a second param :returns: this is a description of what is returned :raises keyError: raises an exception """

5.2 Google风格

""" This is a groups style docs. Parameters: param1 - this is the first param param2 - this is a second param Returns: This is a description of what is returned Raises: KeyError - raises an exception """

5.3 Numpydoc (Numpy风格)

""" My numpydoc description of a kind of very exhautive numpydoc format docstring. Parameters ---------- first : array_like the 1st param name `first` second : the 2nd param third : {'value', 'other'}, optional the 3rd param, by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """

六、一些注释经验

• 注释不是越多越好。对于一目了然的代码，不需要添加注释。
• 对于复杂的操作，应该在操作开始前写上相应的注释。
• 对于不是一目了然的代码，应该在代码之后添加注释。
• 绝对不要描述代码。一般阅读代码的人都了解Python的语法，只是不知道代码要干什么

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持易盾网络。