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 规范）。

立即学习“Python免费学习笔记（深入）”；

• # ✅ 标准函数 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 自动运行验证