Gemini脚本注释提示词：从普通到进阶的完整写法指南

要让Gemini生成的脚本注释兼具可读性与工程实用价值，不应仅停留在“逐行解释代码”层面。基于实战经验，需从注释目的、读者画像、上下文粒度三个维度递进式优化提示词。以下直接阐述各版本具体写法。

基础版：明确告知Gemini“此任务为注释生成”

第一步，在提示词起始处明确任务类型，防止模型默认生成完整脚本。【必须包含“仅添加注释，不修改或重写任何代码”】。此约束不可省略，它是区分“注释任务”与“脚本生成”的核心分界。

第二步，提供待注释的代码片段，并使用```python```等代码块包裹，确保语法结构完整。模型输出质量低常因输入代码本身不规范所致。

第三步，添加一条格式约束：“每行代码上方或右侧添加中文注释，以#开头，不插入多余空行。”此规则虽简单，却能精准解决注释排版混乱的长期痛点。

实用进阶版：调控注释深度与读者视角

方法一：按读者经验分层提示
面向新手的注释，核心在于解释“为何如此实现”；面向维护者的注释，则需强调“修改此处会牵连哪些模块”。例如，可这样书写：“假设读者是刚接手项目的Python中级开发者，请解释该函数为何选用try/except而非if判断，并说明except块中logging.error()参数level的选择依据。”一旦明确读者画像，注释的深度与针对性即刻提升。

方法二：绑定上下文锚点
在提示词中直接引用代码中的变量名、函数名或错误码，迫使注释具体化。例如：“请为check_user_status()内status_code == 403的判断添加注释，阐述其对应OAuth2.0规范中哪一授权拒绝场景。”如此生成的注释将精确映射业务逻辑，而非泛泛描述。

【关键约束】若代码包含硬编码值（例如API超时设为3000），注释必须说明该数值的业务来源，不得仅写“超时时间”。许多团队因硬编码数字缺乏解释而陷入维护困境，无人敢贸然修改。

工程强化版：嵌入团队规范与可维护性要求

第一步，明确注释风格标准。
“遵循Google Python Style Guide第3.8节注释规范，函数级注释必须包含Args、Returns、Raises三段，且Args部分需注明参数是否可为None。”这不仅是风格统一，更直接决定了注释能否通过代码评审。

第二步，注入变更敏感点提示。
“识别出代码中调用外部API的行，并在其注释中标明：①该API当前SLA承诺的P95延迟；②若超时触发降级逻辑，降级返回值在哪个模块定义。”此类注释能帮助团队在故障发生时迅速定位影响范围。

第三步，设置注释自检条件。
“检查所有for循环，若循环体超过4行或包含嵌套if，则必须在循环开始前以# TODO: 注释说明该循环的核心业务意图（不超过15字），例如：# TODO: 合并跨区域库存”。这一自检机制是防止注释流于形式的关键手段。