Python注释和文档字符串是代码可读性、协作效率及自动化工具正常工作的基础：单行注释用#加空格说明“为什么”；多行注释用连续#行；docstring必须用三重双引号顶格写于定义后第一行，包含用途、参数、返回值等关键信息。
Python 注释和文档字符串（docstring）不是可有可无的装饰，而是代码可读性、协作效率和自动化工具（如 Sphinx、IDE 提示、doctest）正常工作的基础。写得规范，别人看得懂，自己半年后也认得出来。
单行注释用 #，紧跟空格，说明“为什么”，而非“做什么”
Python 单行注释以 # 开头，后面必须跟一个空格，再写内容。重点不是重复代码动作，而是解释意图、特殊原因或临时妥协。
-
# ✅ 好：说明决策依据
# 使用 Decimal 避免浮点精度误差，因涉及金额计算 -
# ❌ 差：只是复述代码
# 将 price 转为字符串→ 这行代码本身已经很清楚了 -
# ⚠️ 注意：不要在行尾写注释（尤其复杂逻辑后），易被忽略且难维护
x = x * 1.05 # 加税（5%）→ 推荐提前提取为常量或单独成行
多行注释用连续的 # 行，不用三引号
Python 没有原生多行注释语法。若需注释多行代码或写一段说明，应使用多个 # 行，每行都以 # 开头并后跟空格。不要用 """ ... """ 或 ''' ... ''' 包裹普通注释——那会被解释器当作字符串字面量（哪怕没赋值），可能意外影响性能或被误抓进文档生成工具。
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
-
# ✅ 正确的多行注释
# 这里跳过空行和注释行# 同时忽略开头带空格的行（防缩进干扰） -
# ❌ 错误：看似像注释，实为未使用的字符串
"""跳过空行和注释行忽略开头带空格的行"""
函数/类/模块的 docstring 必须用三重双引号 """，且顶格写在定义下方第一行
docstring 是 Python 官方认可的文档机制，会被 help()、IDE 悬停提示、Sphinx 等直接提取。它必须是字符串字面量，且严格位于定义之后、任何执行语句之前；必须用 三重双引号（"""），不接受单引号或三重单引号（即使语法允许，也不符合 PEP 257 规范）。
-
# ✅ 标准函数 docstring 结构（Google 风格常见）
def calculate_tax(amount: float, rate: float = 0.05) -> float:"""计算含税金额。Args:amount: 税前金额，单位为元rate: 税率，默认为 5%Returns:含税总金额（四舍五入到小数点后两位）"""return round(amount * (1 + rate), 2) -
# ✅ 模块级 docstring 放在文件最顶部（#!/usr/bin/env python 后）
"""工具函数集合：处理日期格式化与金额校验。""" -
# ❌ 错误：缩进、用错引号、位置不对
def func():# 这不是 docstring'''错误：用了单引号''' # 不推荐return True
docstring 内容要简洁实用，包含用途、参数、返回值、异常（如有）
不必长篇大论，但关键信息不能少。PEP 257 建议 docstring 应回答：“这个东西是干什么的？”“怎么用？”“可能出什么错？”
- 用途：首句用一句话概括功能，以动词开头（如“计算…”、“验证…”、“加载…”），结尾不加句号（如果只有一句）
- 参数（Args）：列出每个参数名、类型（可选但推荐）、含义；类型可用 type hints 或文字描述
- 返回值（Returns）：说明返回什么，类型和含义；若无返回，写 “None” 或省略（但建议显式写出）
- 异常（Raises）：如有明确抛出的异常（如 ValueError、TypeError），应注明触发条件
- 示例（Examples）：可选，对复杂逻辑或典型用法很有帮助，还能被 doctest 自动运行验证
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
