How to Write Good Python Comments and Docstrings.
作者：禅与计算机程序设计艺术
1.简介
在编程领域中，Python是一种广受欢迎且功能强大的语言。如今，在高级编程语言中，Python被广泛认为是应用最广泛的工具之一。除了掌握基本语法之外，丰富的第三方库资源则为开发者提供了极大的便利性与灵活性。对于那些刚开始学习Python的新手来说，在编写高质量的注释、生成规范的文档字符串以及塑造良好的代码风格方面可能会遇到诸多挑战与困惑。
本文旨在探讨Python编程中的一些实用经验和相关技巧。旨在帮助读者更有效地学习和应用Python注释与文档字符串的相关知识与使用方法。具体涵盖了以下几个关键点：
- 编写注释和文档字符串的主要目的是为了提高代码的质量和可维护性。
- 注释在软件开发中的作用和意义体现在它能够帮助其他开发者理解代码逻辑以及提供必要的上下文信息。
- 编写高质量注释的标准是确保其准确性和一致性，并且能够清晰地传达相关信息。
- 文档字符串指的是用于描述程序功能、变量含义或其他重要信息的文字说明。
- 撰写有效的文档字符串需要遵循一定的规范与结构。
- 在PyCharm中自动生成文档的具体步骤包括配置插件以及利用其智能建议功能来生成完整的说明内容。
- 在实际开发中遵循编写规范与风格指南才能写出高质量的注释和文档字符串。
- 探讨未来发展方向及面临的主要挑战。
该文章旨在为具备一定编程基础的读者提供系统化的Python知识学习资源。
本文总结了作者长期致力于Python编程教学与实践研究的经验，并归纳并深化了其中的理论与方法。旨在为读者提供有价值的学习资料，并有助于引导读者在学习过程中不断进步。
2. 基本概念和术语
- Python: 是一种广泛应用于各个领域的开源高级编程语言。
- 模块（Module）: 在Python环境中独立运行的一份代码。
- 函数（Function）: 是一个接收输入并返回输出结果的操作逻辑。
- 方法（Method）: 是类中定义的行为方式。
- 参数（Parameter）: 是函数或方法接收的具体输入值。
- 注释（Comment）: 为了帮助他人理解代码而添加的文字说明。
- 方法是用来访问和修改对象属性的方式。
- 参数是被传递给调用者的具体输入值。
- 注释是为了让别人更容易理解程序而添加的文字说明。
- 文档字符串用于记录模块、类、函数、方法的信息帮助用户快速了解这些元素的功能和用法。
3. 概念解释
3.1 为何要写注释？
所有的程序都应当配备相应的说明文字；每一个代码行都是一个独立的功能单元；如果缺乏足够的说明文字；其他开发者将难以准确理解其运行机制；即使是在多年之后重新审视这段代码时；这些说明文字能够为你提供新的理解视角；所以写出高质量的说明文字至关重要
另外，在线编辑器中输入一些测试数据后发现
最终而言，在代码被同行或其他工程师进行审核和参考的情况下，编写清晰的注释仍然能有效降低潜在的错误。他人的理解和掌握通常会比个人的理解更加深刻和全面。
3.2 注释的作用
注释有两种主要作用：
- 提供额外的信息；
- 描述正在执行的逻辑，让别人容易理解代码。
1.提供额外的信息
评论可以提供额外的信息，例如：
a = 1 + 1 # Add two numbers together.
print(a) # Output the result.
代码解读虽然这两个注释仅限于简要说明代码的功能和用途，并不能提供深入的技术细节或完整的实现思路。但对于那些较为复杂的代码项目而言，在编写和理解过程中这些注释仍然具有重要意义
2.描述正在执行的逻辑
另一方面地讲，在编写代码时添加注释不仅有助于提高可读性还能让其他人迅速掌握代码的运行流程举个实例来说
if age > 18:
print("You are old enough to vote.")
elif age >= 16: # Check if age is between 16 and 18 inclusive.
print("You can still vote in some states.")
else: # If not, say that you need a driver's license.
print("Sorry, you need a driver's license to vote.")
代码解读这些注释对代码的运行逻辑进行了说明，并不费劲就能理解。如果省去注释的话，则可能会导致以下问题：
- 基于国际法规定的原则进行判断的前提下, 未考虑到中国特殊情况。
- 当读者未能理解第一句话的内容时, 可能会转向查阅相关法律法规, 但即便如此也会因记不清具体内容而导致认识偏差。
- 当其他同事查看注释时, 他们仅需了解"年龄超过18岁"这一条件就足以明白代码的意义。
3.3 好的注释应该怎么写？
好的注释应当具备以下几个特性：
为关键部分添加详细注释，并确保这些注释能够清晰传达相关背景信息。
在注释中提供代码背景信息的同时遵循统一的设计规范。
明确定义代码所需的输入参数及其预期输出结果。
1.对重要的部分进行注释
注解应着重应用于那些具有重要性的代码块而不是冗余的部分例如在某些情况下仅几行简单的指令无需附加详细的说明这是因为这些指令通常易于理解和执行而对于较为复杂的函数体编写详尽的注解可能耗时较长这可能源于这段代码本身具有较高的复杂度难以被迅速理解
2.在注释中给出代码的上下文
良好的注释中包含了代码的上下文。举个例子：
# This loop calculates the sum of all integers from i=1 to n using a for loop.
sum_of_integers = 0
for i in range(1,n+1):
sum_of_integers += i
代码解读对于这种类型的注释存在不足之处。由于缺乏相关的上下文信息，在理解循环体中变量i的具体作用时存在一定的困难。改进后的注释应详细说明循环的执行目的、作用范围，并明确说明所使用的变量。
# Calculate the sum of all integers from i=1 to n.
# The variable `i` represents each integer being added up.
sum_of_integers = 0
for i in range(1,n+1):
sum_of_integers += i
代码解读3.使用一致的样式和格式
如果有多个注释，应该保持一致的样式和格式。比如：
# Set the value of x to be one plus the length of y minus three times z.
x = len(y) - 3*z + 1
# Multiplying y by four and adding it to itself five times results in the final value of w.
w = (y * 4) + (y * 4) + (y * 4) + (y * 4) + (y * 4)
代码解读这些注释都遵循了一致的结构。
4.描述代码所期望的输入和输出
此外，在代码块注释中应当详细说明该代码的功能模块及其运行流程，并明确标注相关变量的作用域与数据类型。例如，在函数设计时, 应尽可能详细地说明所需输入参数, 并确保其返回值应尽量清晰地进行阐述
def calculate_area(base, height):
"""Calculate the area of a triangle given its base and height.
Args:
base (float): The length of the triangle's base.
height (float): The height of the triangular shape.
Returns:
float: The area of the triangle.
"""
return 0.5 * base * height
代码解读3.4 什么是文档字符串？
文档字符串（docstring）作为一个字符串元素存在于Python代码中，并且是其重要组成部分之一。
它通常放置于模块或类等作用域的首位，并由一对三引号括起来。
在定义这些结构时（如模块或类），必须包含一个相应的说明。
文档字符串能够帮助你为你所创建的各种元素提供详尽的说明。通过使用文档字符串自动生成代码文档（例如HTML文件），你可以获得所有模块、类、函数和方法的一一对应及其详细说明。
3.5 如何编写文档字符串？
模块的文档字符串应详细描述其功能与用途，请确保所有接口均配有相应的文档说明以提高可维护性与可理解性。在此基础上，请提供具体的输入参数及其对应的输出结果说明以帮助开发者准确使用相关功能；同时建议在必要时添加示例代码来进一步阐述各组件的工作原理与实现细节以减少歧义与误解风险。
1.模块文档字符串
"""This module contains functions for performing basic math operations."""
代码解读2.类文档字符串
class Calculator:
"""A class used to perform arithmetic calculations on numbers.
Attributes:
current_value (int or float): The current value stored in the calculator.
Methods:
add(self, number): Adds a number to the current value.
subtract(self, number): Subtracts a number from the current value.
multiply(self, number): Multiplies the current value by a number.
divide(self, number): Divides the current value by a number.
"""
def __init__(self):
self.current_value = 0
def add(self, number):
self.current_value += number
def subtract(self, number):
self.current_value -= number
def multiply(self, number):
self.current_value *= number
def divide(self, number):
if number!= 0:
self.current_value /= number
else:
raise ValueError('Cannot divide by zero.')
代码解读3.函数文档字符串
def add(number1, number2):
"""Adds two numbers together.
Args:
number1 (int or float): The first number to add.
number2 (int or float): The second number to add.
Returns:
int or float: The sum of the two input numbers.
"""
return number1 + number2
代码解读4.方法文档字符串
class Rectangle:
"""A rectangle with width and height attributes.
Attributes:
width (float): The width of the rectangle.
height (float): The height of the rectangle.
Methods:
get_area(self): Calculates the area of the rectangle.
get_perimeter(self): Calculates the perimeter of the rectangle.
"""
def __init__(self, width, height):
self.width = width
self.height = height
def get_area(self):
"""Calculates the area of the rectangle.
Returns:
float: The area of the rectangle.
"""
return self.width * self.height
def get_perimeter(self):
"""Calculates the perimeter of the rectangle.
Returns:
float: The perimeter of the rectangle.
"""
return 2 * (self.width + self.height)
代码解读3.6 如何在PyCharm中使用自动生成的文档？
因为Python展现出卓越的易用性，在自动生成代码文档的过程中，文档字符串发挥着举足轻重的作用。PyCharm包含了一系列功能模块来辅助生成代码文档
按下Ctrl键后，在文档字符串左侧空白处点击以创建一个空白文档字符串。
在右键菜单中选择'Generate documentation...'选项。
在Project视图中依次点击File > Settings > Tools > Python Integrated Tools > Generate Sphinx Documentation。
在选择了之后，请您设置一下输出目录，并点击Apply & Close按钮以完成配置。
3.7 正确的注释和文档字符串的实践
如果你正在编写注释，那么务必遵守下面的原则：
- 规范化的代码有助于提升可读性和维护性。
- 避免在非技术性内容中混入中文注解。
- 确保所写的说明能够清晰传达程序功能和逻辑。
- 定期更新说明以保持描述的准确性。
- 确保所有说明与对应的程序模块高度相关。
- 避免将无意义的内容混入说明中。
- 编写详细的文档是必须的。
- 采用名词形式来描述程序功能而非动词表达。
如果你正在编写文档字符串，那么务必遵守下面的原则：
所有模块、类以及函数和方法都应配备详细的文档注释。
在模块和类的起始位置应放置相应的注释说明。
注释应完整且清晰地阐述功能目的及操作步骤等关键信息。
注释需简洁明了地传达核心功能及操作流程。
示例代码片段可以帮助读者直观理解其用途。
注释变更需与对应代码同时更新。
确保注释既实用又简洁明了。