Python3 注释编写完全指南从基础规范到高效实践注释这事儿说大不大说小不小。写好了帮你省三个月后的记忆写砸了比不写还坑人。这篇把注释的规矩、套路和坑一次说清楚。WEB项目地址演示地址安卓APP下载地址演示地址① 注释的核心价值与适用场景解析注释到底是写给谁看的写给你的队友看也写给三个月后的自己看。代码是写给计算机执行的但代码也是给人读的。一个函数干了什么事、参数有什么约束、返回值什么格式——这些信息光靠看代码不一定能一眼看出来。注释就是用来补上这段“代码没写明白”的信息。什么时候该写注释复杂的业务逻辑比如订单金额的计算规则、折扣叠加的顺序非常规的实现方式比如“这里故意不用算法 A 而用算法 B因为 A 在大数据量下会 OOM”对外暴露的 API / 公共函数别人要调你的代码得知道怎么用临时的处理方案比如“TODO: 等后端接口上线后替换这里的 mock 数据”什么时候不用写注释代码本身就能说清楚的事别重复一遍。比如i 1旁边写“i 加 1”——这就是废话。② 单行注释的正确写法与快捷操作Python 的单行注释用井号#开头。从#开始到这一行结束的所有内容解释器都忽略。# 计算订单总价包含税费和运费totalsubtotal*1.08shipping_fee两条硬规矩规矩一#后面跟一个空格再写文字。这是 PEP 8 官方推荐的写法几乎所有 Python 项目都遵守。# 好的写法# 坏的写法井号后面没空格规矩二注释和代码至少空两个空格。如果是写在代码行末尾的注释#前面至少空两格。price99.9# 原价单位美元discount_rate0.2# 折扣率目前全场八折快捷操作大多数编辑器里选中多行按Ctrl /Windows/Linux或Cmd /Mac可以批量加/取消单行注释。这个快捷键平时用得最多——调试时临时屏蔽一段代码一秒钟搞定。③ 多行注释与文档字符串的区别用法很多教材说 Python 的多行注释是用三个引号或括起来——这个说法其实不准确。三个引号包裹的字符串如果没赋值给任何变量解释器确实会忽略它效果上像注释。但它的本质是字符串字面量不是真正的注释语法。 这是一段被三个引号括起来的文字。 解释器会把它当作一个字符串常量 但不赋值的话就直接丢弃了。 真正靠谱的多行注释方式每行前面都加#。这是 PEP 8 推荐的做法也是绝大多数 Python 项目的实际写法。# 这里实现了一个简单的缓存淘汰策略。# 当缓存大小超过 max_size 时# 移除最早加入的那个条目。defevict_cache(cache,max_size):...什么时候用三个引号用三个引号写正式的文档字符串docstring专门给函数、类、模块写说明文档用的。它不是注释是文档。下面第④节细说。④ 函数与类文档字符串的标准结构文档字符串docstring是写在函数或类定义下面的第一行用三个双引号括起来。它和注释最大的区别是注释是给人看的docstring 可以被程序读取。defcalculate_discount(original_price,member_level):根据会员等级计算折扣后的价格。 Args: original_price: 原价单位元正数。 member_level: 会员等级gold / silver / bronze。 Returns: 折扣后的价格单位元。如果原价无效则返回 -1。 Raises: ValueError: 会员等级不在支持范围内时抛出。 iforiginal_price0:return-1# ... 具体实现标准结构包含这几块第一行一句话说清楚函数是干嘛的空一行Args:列出每个参数说明类型和含义Returns:说明返回值包括什么情况返回什么Raises:可选什么情况会抛什么异常用help()直接看在交互式环境里执行help(calculate_discount)上面写的 docstring 会直接打印出来。这才是 docstring 的真正价值——不用打开源码就能知道怎么用。常见的 docstring 风格Google 风格上面示例那种可读性最好推荐新手用NumPy/SciPy 风格更详细参数描述独占一行适合科学计算项目SphinxreST风格用:param name:这种格式和 Sphinx 文档生成工具配合用新手优先用 Google 风格够用、好读。⑤ 代码逻辑注释的编写最佳实践写逻辑注释的核心原则就一条解释“为什么”而不是“是什么”。# 差评代码已经说明了一切# 将 total 乘以 0.9totaltotal*0.9# 好评说明背后的业务原因# VIP 用户享受 9 折优惠这个规则 2023 年 6 月上线totaltotal*0.9对复杂条件判断加注释# 只有已登录、且账户余额大于 100 元、且最近 30 天有消费记录的用户# 才发放优惠券。这是运营部门 2025 年 Q1 的新规。ifuser.is_authenticatedanduser.balance100anduser.last_purchase_days30:grant_coupon(user)这种注释的价值在于三个月后维护这段代码的人可能是你自己一看就知道为什么有这些条件而不是小心翼翼地猜“动了这个会不会炸”。对“非常规写法”加注释# 这里用 while 循环而不是 for是因为列表在遍历过程中会动态变长# for 循环无法正确处理动态变化的长度。idx0whileidxlen(queue):process(queue[idx])idx1⑥ 避免无效注释与过度注释的技巧无效注释长什么样xx1# x 增加 1# 初始化计数器counter0这种注释纯属凑数。变量名本身就说明了一切。删了它代码更清爽。过度注释长什么样# 第一步打开文件fileopen(data.txt)# 第二步读取所有行linesfile.readlines()# 第三步遍历每一行forlineinlines:# 第四步去掉末尾换行符lineline.strip()# 第五步打印这一行print(line)把“步骤”这种流程性的东西当注释每行代码配一句解释——纯属噪音。真正有用的不是“做什么”而是“为什么这么做”。判断一个注释该不该留问自己三个问题删掉这个注释代码还能不能一眼看懂这个注释补充了代码没有表达的信息吗如果我不写这个注释维护者会误解这段代码吗三个问题都回答“是”才值得写注释。⑦ 利用注释进行临时调试的方法注释在调试的时候特别有用——把代码“关掉”比删掉安全。屏蔽某一段代码选中要屏蔽的代码按Ctrl /Mac 是Cmd /整段变成注释。想恢复再按一次取消注释。# 发邮件通知用户# send_notification_email(user, order)# 记录日志到数据库# log_to_database(event)用注释做“开关”有时候你想快速切换两种实现可以这样# 正式环境用真实 APIresultcall_real_api(params)# 测试环境用模拟数据上面那行注释掉下面这行取消注释# result mock_response(params)用TODO标记待办这不算严格意义的注释但实际工作中每天都在用defprocess_order(order):# TODO: 等支付接口稳定后加一个重试逻辑# FIXME: 这里的税率写死了 0.08需要改成从配置读取# BUG: 订单金额为 0 时这里会除零下个版本修...多数编辑器会把TODO和FIXME高亮显示一眼就能看到哪些地方还没做完。⑧ 主流编辑器注释快捷键大全编辑器 / IDE注释/取消注释单行块注释VS CodeCtrl /Win /Cmd /Mac同上PyCharmCtrl /Win /Cmd /MacCtrl Shift /Win /Cmd Shift /MacSublime TextCtrl /Win /Cmd /MacCtrl Shift /Win /Cmd Shift /MacVimgc在 Visual 模式下用插件或:s/^/#/Jupyter NotebookCtrl /Win /Cmd /Mac同上IDLE自带Alt 3注释 /Alt 4取消注释无快捷键手动加#记住最通用的那组就行Ctrl /或Cmd /通吃 90% 的编辑器。⑨ 团队协作中的注释风格统一规范一个人写代码怎么都行一群人写代码必须统一规矩。以下是实际团队里最实用的几条1. 注释用英文还是中文看团队情况。全员英文能力过关就用英文——兼容性最好GitHub 开源项目也方便。国内团队用中文完全没问题关键是统一不要中英混用。2. 用#加空格的写法前面说了#后面跟一个空格。所有人统一。3. docstring 统一风格定一种 docstring 风格全团队用同一种。新手团队建议直接定 Google 风格上手快。4. 文件头注释有些团队要求在文件开头写版权、作者、创建日期等信息#!/usr/bin/env python3# -*- coding: utf-8 -*-# Copyright (c) 2026 YourCompany. All rights reserved.实际上现在 Python 3 默认 UTF-8 编码第二行# -*- coding: utf-8 -*-基本不需要了。文件头要不要写、写什么、怎么写按团队自己的规矩来。5. 用 linter 自动检查在项目里配置flake8或pylint把注释规范加进去。不符合规范的代码提交时会报警告——省得 code review 时候吵。⑩ 常见注释误区与修正案例演示误区一注释和代码不同步代码改了注释没改——这是最坑的情况。注释说“返回用户列表”实际上返回的是字典。看注释的人被带沟里。修正修改代码的同时必须同步更新注释。做不到就不要写注释错误注释比没注释更可怕。误区二把注释当草稿纸# 这个函数写得比较烂后面再优化# 感觉这里可以加个缓存但我还不确定# 这个地方纠结了好久这种情绪化的自言自语不该出现在正式代码里。要么把思路理清楚再写要么删掉这些废话。误区三注释缩写过多# init db conn, retry if fail“db” 还算常见“init”“conn”“retry” 也还行。但有些团队内部用的生僻缩写新人完全看不懂。注释是为了让人读懂不是加密。误区四docstring 写得太简略defparse_config(filepath):解析配置文件。这等于没写。至少要说清楚配置文件是什么格式、解析失败怎么办、返回什么结构。一组前后对比修改前defget_data(id):# get data by idresrequests.get(urlid)# parse jsondatares.json()# return datareturndata[result]修改后defget_user_profile(user_id):从用户中心 API 获取用户基本信息。 Args: user_id: 用户的唯一标识 ID字符串格式。 Returns: 包含用户昵称、头像 URL、注册时间的字典。 如果用户不存在API 返回 404本函数返回 None。 Raises: requests.RequestException: 网络请求失败时抛出。 api_urlf{USER_API_BASE}/profile/{user_id}responserequests.get(api_url)ifresponse.status_code404:returnNoneresponse.raise_for_status()payloadresponse.json()returnpayload.get(result)修改后的代码变量名自解释、docstring 完整、逻辑清晰、基本不需要额外的行内注释。这才是注释该有的样子——该写的地方写透不该写的地方一句废话都没有。