Python代码注释规范与DocStrings实战指南

代码注释基础与分类

一、代码注释介绍

• 注释是对代码内容的解释与说明，旨在降低理解门槛，使他人能更轻松地掌握代码意图。
• 在编写程序时，注释用于对特定语句、代码段或函数进行提示和解释，从而显著提升程序代码的可读性。
• 对于包含复杂处理逻辑的代码，有效注释的比例应保持在20%以上。

二、代码注释分类

行注释：位于符号后的单行内容不会被编译器处理或显示。

块注释：被特定符号包裹的整个代码块部分均不会被编译执行。

Python注释语法基础

三、python代码注释基础

在Python中，使用井号（#）标识单行注释。单行注释可独立成行置于被注释代码上方，也可置于语句或表达式末尾。示例如下：

name = 'xiaohong' # 单行注释

# 单行注释 name = 'xiaohong'

Python支持使用三个单引号（'''）或三个双引号（"""）进行多行注释，适用于内容较长、单行无法容纳的情况。示例如下：

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

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

DocStrings文档字符串详解

四、DocStrings介绍与使用

4.1 DocStrings介绍

文档字符串（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主流编写风格

五、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语法，他们更关注代码的具体用途而非语法细节。

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