我要评论一、注释类型
单行注释（#）
概念定义
单行注释是 python 中用于在代码中添加说明性文字的一种方式。
以 # 开头，其后的内容在程序运行时会被 python 解释器忽略，仅作为代码的注释供开发者阅读。
使用场景
- 解释代码功能：在复杂的代码行上方或右侧添加注释，说明代码的作用。
- 临时禁用代码：调试时，可以用
#暂时屏蔽某行代码，避免删除。 - 标记待办事项：例如
# todo: 优化算法。
注意事项
- 不要过度注释：清晰的代码本身是最好的注释，仅对复杂逻辑或特殊设计添加注释。
- 避免废话注释：如
# 赋值给变量这类无意义的注释。 - 注释符号后需加空格：规范的写法是
# 注释内容，而非#注释内容。
示例代码
# 计算圆的面积（单行注释在代码上方）
radius = 5
area = 3.14 * radius ** 2 # 单行注释在代码右侧
# 调试时临时禁用代码
# print("这行不会执行")
多行注释（三引号）
概念定义
在python中，三引号（'''或"""）可以用来创建多行字符串，但通常也被用作多行注释。
虽然python官方推荐使用#进行单行注释，但三引号在多行注释场景下非常实用。
使用场景
- 需要注释多行代码或文本时
- 为函数、类或模块编写详细的文档字符串（docstring）
- 临时禁用大段代码进行调试
常见误区或注意事项
- 三引号实际上是字符串，不是真正的注释语法，因此会占用少量内存
- 如果三引号字符串没有被赋值给变量，解释器会忽略它，效果类似注释
- 在函数或类定义后的第一个三引号字符串会被识别为docstring
示例代码
'''
这是一个多行注释的示例
可以跨越多行
不会被python执行
'''
def example_function():
"""这是函数的文档字符串(docstring)
用于说明函数的功能和用法
"""
pass
"""
也可以使用三个双引号
作为多行注释
"""
文档字符串（docstring）
概念定义
文档字符串（docstring）是python中用于解释代码功能、参数、返回值等信息的字符串。
它通常位于模块、函数、类或方法的开头，用三引号（'''或"""）包裹。
docstring可以通过__doc__属性访问，并且可以被工具（如help()函数或文档生成工具）解析。
使用场景
- 函数/方法说明：描述函数的功能、参数、返回值和可能的异常。
- 类说明：解释类的用途、属性和方法。
- 模块说明：说明模块的功能、包含的类和函数等。
常见误区或注意事项
- 与注释混淆：docstring是字符串，而注释是以
#开头的单行说明。docstring更正式且可被工具解析。 - 多行docstring格式：第一行通常是简短描述，接着是空行，然后是详细说明。
- 缩进问题：docstring的缩进必须与代码块一致。
示例代码
def add(a, b):
"""return the sum of two numbers.
args:
a (int): first number.
b (int): second number.
returns:
int: sum of a and b.
"""
return a + b
# 访问docstring
print(add.__doc__)
help(add)
输出：
return the sum of two numbers.
args:
a (int): first number.
b (int): second number.
returns:
int: sum of a and b.
二、注释内容规范
函数/方法注释
概念定义
函数/方法注释是指在python代码中，对函数或方法的功能、参数、返回值等进行说明的文档字符串（docstring）。
它通常位于函数定义的内部，使用三引号（'''或"""）包裹。
使用场景
- 代码可读性：帮助其他开发者快速理解函数的功能和用法。
- 自动生成文档：工具如sphinx或pydoc可以通过解析docstring生成api文档。
- ide支持：现代ide（如pycharm、vscode）会显示docstring，提供代码提示和补全。
常见误区或注意事项
- 格式不统一：建议遵循pep 257规范，或使用google/numpy风格的docstring格式。
- 内容不完整：避免仅写简单描述，应包含参数、返回值和可能的异常说明。
- 过度注释：对于简单函数，避免冗长的注释，保持简洁。
示例代码
def calculate_area(length, width):
"""
计算矩形的面积。
args:
length (float): 矩形的长度。
width (float): 矩形的宽度。
returns:
float: 矩形的面积（length * width）。
raises:
valueerror: 如果length或width为负数。
"""
if length < 0 or width < 0:
raise valueerror("长度和宽度必须为正数")
return length * width
类注释
概念定义
类注释（class docstring）是python中用于解释类功能和用法的文档字符串，通常位于类定义之后、方法定义之前。
它遵循pep 257规范，使用三重引号（"""或'''）包裹。
使用场景
- 说明类的整体功能和设计目的
- 描述类的公共接口和重要方法
- 作为自动生成api文档的基础（如sphinx）
- 帮助其他开发者快速理解类的用途
常见误区或注意事项
- 避免只写"这是一个xx类"等无意义的描述
- 不要与
__init__方法的文档混淆 - 多行文档字符串时，第一行应为简短摘要
- 遵循项目约定的文档风格（如google风格、numpy风格等）
示例代码
class rectangle:
"""表示二维矩形的类。
该类提供了计算面积和周长的方法，
并支持比较两个矩形的大小。
attributes:
width (float): 矩形的宽度
height (float): 矩形的高度
"""
def __init__(self, width, height):
self.width = width
self.height = height
def area(self):
"""计算并返回矩形的面积。"""
return self.width * self.height
模块注释
概念定义
模块注释是python模块顶部的多行字符串，用于描述模块的功能、作者、版本等信息。
它通常位于文件开头，在import语句之前，用三引号("""或''')包裹。
使用场景
- 为模块提供文档说明
- 帮助其他开发者快速理解模块用途
- 可以通过
help()函数或__doc__属性查看 - 自动生成文档工具（如sphinx）会读取这些注释
常见注意事项
- 模块注释应该是多行字符串（使用三引号）
- 第一行应该是模块的简要描述
- 空一行后可以添加更详细的描述
- 可以包含作者、版权、版本等信息
- 不要与函数/类的docstring混淆
示例代码
"""
这是一个计算器模块
提供基本的加减乘除运算功能，支持整数和浮点数计算。
作者: python学习者
版本: 1.0.0
最后更新: 2023-10-01
"""
def add(a, b):
"""返回两个数的和"""
return a + b
# 其他函数...
代码块注释
概念定义
代码块注释是指在python中使用特定语法对一段连续代码进行说明的注释方式。
它通常用于解释一个完整功能模块或复杂逻辑的实现。
使用场景
- 解释函数或类的整体功能
- 说明复杂算法实现步骤
- 描述代码块的业务逻辑
- 标记待修改或待优化的代码区域
常见误区
- 过度注释：不应为显而易见的代码添加冗余注释
- 注释与代码不同步：修改代码后未更新相应注释
- 使用单行注释代替代码块注释：导致注释分散不连贯
示例代码
"""
这是一个计算斐波那契数列的函数
参数：
n: 要生成的数列项数
返回值：
包含n个斐波那契数的列表
"""
def fibonacci(n):
a, b = 0, 1
result = []
for _ in range(n):
result.append(a)
a, b = b, a + b
return result
多行代码块注释示例
# ======================================
# 这段代码处理用户登录验证流程：
# 1. 检查用户名是否存在
# 2. 验证密码是否匹配
# 3. 记录登录日志
# ======================================
if user_exists(username):
if check_password(username, password):
log_login_attempt(username, true)
return true
else:
log_login_attempt(username, false)
return false
行内注释
概念定义
行内注释是指在代码行的末尾或中间添加的简短注释，用于解释该行代码的作用或意图。
通常用于对单行代码进行快速说明。
使用场景
- 解释复杂或不易理解的代码片段
- 临时标记需要后续修改的代码
- 说明变量的特殊用途
- 记录代码的修改原因
常见误区或注意事项
- 避免过度使用行内注释，只在必要时添加
- 注释内容应简洁明了，避免冗长
- 不要用行内注释解释显而易见的代码
- 确保注释与代码保持同步更新
- 在python中，行内注释前应保留至少两个空格
示例代码
x = 5 # 初始化计数器 y = x * 2 # 计算双倍值 # 不推荐的写法： z = x + y # 把x和y相加
三、文档字符串标准
google风格
概念定义
google风格（google style）是指google公司为python代码制定的编码规范，旨在保持代码的一致性和可读性。
它是对pep 8（python官方编码规范）的补充和扩展，特别适用于大型项目和团队协作。
使用场景
- 团队协作：当多个开发者共同维护一个项目时，统一的编码风格可以减少理解成本。
- 开源项目：遵循google风格的开源项目更容易被其他开发者理解和贡献。
- 代码审查：在代码审查中，google风格可以作为标准化的参考依据。
常见误区或注意事项
- 与pep 8的冲突：google风格在某些细节上与pep 8不同（如行长度限制为80字符，而google风格允许100字符），需注意区分。
- 过度格式化：不应为了完全符合规范而牺牲代码的逻辑清晰性。
- 工具支持：可以使用
yapf（google开发的自动格式化工具）来辅助遵循规范。
示例代码
# google风格示例：函数文档字符串（docstring）
def calculate_sum(a, b):
"""计算两个数的和。
args:
a (int): 第一个加数。
b (int): 第二个加数。
returns:
int: 两个数的和。
"""
return a + b
关键点说明
- 文档字符串：使用三重引号，明确说明参数类型和返回值。
- 命名规范：函数名使用小写字母和下划线（
snake_case）。 - 缩进：使用4个空格（与pep 8一致）。
numpy风格
概念定义
numpy风格指的是在python中使用numpy库时遵循的一系列编码惯例和最佳实践。
这种风格强调向量化操作、避免显式循环，并充分利用numpy的广播机制和高效数组操作。
使用场景
- 科学计算和数值分析
- 机器学习数据处理
- 图像处理
- 大规模数组操作
- 需要高性能数学运算的场景
常见误区或注意事项
- 避免python原生循环：numpy的向量化操作比python循环快得多
- 正确使用广播机制：理解广播规则可以避免维度不匹配错误
- 注意内存使用：大数组操作可能导致内存问题
- 避免不必要的数组拷贝：使用视图(view)而不是副本(copy)可以提高性能
- 数据类型选择：选择合适的数据类型可以节省内存和提高速度
示例代码
import numpy as np # 创建数组 - 使用np.array而不是python列表 arr = np.array([1, 2, 3, 4, 5]) # 向量化操作 - 避免显式循环 squares = arr ** 2 # 正确方式 # 而不是 [x**2 for x in arr] # 广播示例 matrix = np.array([[1, 2, 3], [4, 5, 6]]) result = matrix * np.array([10, 100, 1000]) # 自动广播 # 高效索引 even_elements = arr[arr % 2 == 0] # 布尔索引 # 使用内置函数 sum_total = np.sum(arr) # 比sum(arr)更快 # 避免不必要的拷贝 view = arr[1:4] # 创建视图，不复制数据
restructuredtext风格
概念定义
restructuredtext（简称rest或rst）是一种轻量级的标记语言，主要用于编写技术文档。
它是python文档工具链（如sphinx）的标准格式，具有易读性和结构化特性。
使用场景
- python项目文档（通过sphinx生成html/pdf）
- 技术文档的版本控制
- api文档编写
- 跨平台文档转换（支持输出html/latex等格式）
常见注意事项
- 缩进必须保持一致（推荐使用空格）
- 空行分隔不同结构元素
- 标题下划线长度必须≥标题文本长度
- 特殊符号（如*）需要转义时使用反斜杠
基础语法示例
主标题
======
二级标题
--------
* 项目符号列表
* 第二个项目
1. 数字列表
2. 第二项
代码块::
def example():
print("使用4空格缩进")
.. note::
这是一个提示框
`超链接 <https://python.org>`_
表格示例
+------------+-----------+ | header 1 | header 2 | +============+===========+ | cell 1 | cell 2 | +------------+-----------+ | row 2 | data | +------------+-----------+
跨文档链接
参见 :doc:`other_page` 或 :ref:`section-label`
epytext风格
概念定义
epytext是一种轻量级的标记语言，主要用于python文档字符串（docstring）的格式化。
它是epydoc工具默认支持的格式，用于生成api文档。
epytext使用简单的标记符号（如@、l{}等）来标注文档中的特殊元素。
使用场景
- 为python函数、类、模块编写规范的文档字符串
- 需要生成api文档时（配合epydoc工具使用）
- 在代码中标记参数、返回值、异常等元素
常见注意事项
- 标记符号必须紧跟在行首或前导空格后
- 避免过度嵌套标记
- 参数描述中的类型说明是可选的
- 与restructuredtext不同，epytext使用
@符号而不是:作为标记前缀
示例代码
def calculate_area(width, height):
"""
calculate the area of a rectangle.
@param width: the width of the rectangle (in meters)
@type width: float
@param height: the height of the rectangle (in meters)
@type height: float
@return: the calculated area
@rtype: float
@raise valueerror: if either dimension is negative
"""
if width < 0 or height < 0:
raise valueerror("dimensions cannot be negative")
return width * height
总结
以上为个人经验，希望能给大家一个参考，也希望大家多多支持代码网。
发表评论