冗余无用注释指与代码行为完全重复、已过时或纯占位无信息量的注释，包括初始化/返回类重复注释、空行注释、未处理的连续TODO及无效三引号块；需结合ast解析与tokenize定位，按规则安全删除，保留结构与协作标记。
识别“冗余无用注释”的实际判断标准
所谓“冗余无用”，不是指语法上非法的注释，而是指那些**与代码行为完全重复、已过时、或纯占位无信息量**的注释。常见类型包括：# 初始化变量（后面是 x = 0）、# 返回结果（后面是 return res）、空行注释 #、连续多行 # TODO 但从未被处理、以及被 """ 包裹却未形成有效 docstring 的块注释。
Python 自身不提供“注释语义分析”能力，必须靠规则 + 模式匹配。别指望大模型实时扫描——它既慢又不可控，且无法保证一致性。
- 优先匹配行首
#后紧接空格 + 低信息词（如init、return、set、get、temp、dummy） - 跳过以
# TODO、# HACK、# FIXME开头的行（即使没后续内容，也视为有意图） - 跳过位于函数/类定义正上方、且长度 ≥ 3 行的
"""..."""块（哪怕内容空，也可能是预留 docstring） - 对单行
"""或'''注释，若内容为空或仅含空格/换行，视为冗余
用 ast 解析比正则更可靠，但有局限
直接用正则删注释风险极高：可能误删字符串里的 #（如 "http://example.com#anchor"），或破坏多行字面量。真正安全的做法是先用 ast.parse() 获取语法树，再遍历 ast.Constant 和 ast.Expr 节点提取字面量级注释位置。
注意：ast 本身不保留注释节点（PEP 723 之前），所以只能靠解析器前的源码预处理——推荐组合使用 ast + tokenize：
立即学习“Python免费学习笔记（深入）”；
- 用
tokenize.generate_tokens()扫描所有tokenize.COMMENT类型 token，拿到精确行列号 - 用
ast.parse()构建结构，确认该注释是否紧邻某条语句（比如是否在Assign节点前一行且无空行隔开） - 只删除满足“孤立、短、语义重复”的注释；保留嵌入在逻辑块中、或跨多行的注释（如配置说明）
示例片段（获取注释位置）：
import tokenize from io import BytesIO <p>def get_comment_lines(source: str) -> set: lines = set() tokens = tokenize.tokenize(BytesIO(source.encode()).readline) for tok in tokens: if tok.type == tokenize.COMMENT: lines.add(tok.start[0]) return lines
删除时必须保留原始缩进和换行结构
很多脚本直接 re.sub(r'^\s*#.*$', '', line)，结果把注释删掉后留下空行或错位缩进，导致后续代码缩进异常甚至语法错误。正确做法是：对每一行，只替换注释部分为等长空格（或空字符串），但保持该行总长度不变，或确保删后仍为合法 Python 行。
- 对行内注释（如
x = 1 # init counter），只删#及之后内容，保留前面空白 - 对独占一行的注释，整行替换为空字符串，但要检查前后是否有连续空行——避免生成多余空行堆叠
- 永远不要用
file.write()覆盖原文件；先写到临时文件，再os.replace()原子替换 - 加
--dry-run参数默认只打印将删哪些行，不写入
真实项目中容易被忽略的边界情况
自动化删注释最常翻车的地方不在逻辑，而在环境和协作假设上：
-
.pyi文件、Jupyter Notebook 的# %%cell marker、类型存根里的注释不能动 - 某些团队用注释标记测试范围（如
# pytest: disable=too-many-arguments），这类需白名单匹配 -
setup.py或pyproject.toml里内联的 Python 片段（如setup(..., ext_modules=[...])）也可能含注释，但不属于主代码路径 - Git 未暂存的修改会被覆盖——脚本运行前应提醒用户
git status并建议先提交或 stash
没有通用“安全删除”方案。每个项目得配一个 .commentignore 文件，声明哪些路径/模式跳过处理，比如 tests/**、docs/conf.py、**/migrations/*.py。
