先说明一个基础认知：使用DeepSeek生成脚本时，注释示例并非可有可无的装饰——它直接决定了代码结构是否清晰、变量命名是否合理、边界处理是否完整。如果提示词中缺乏示例，模型往往会按照自身理解“自由发挥”，比如将数据库连接直接写在函数内部，或者遗漏关键的异常捕获逻辑。这些在开发阶段也许能正常运行，但一旦部署到生产环境就容易暴露问题。

为什么注释示例如此重要

DeepSeek对“注释即契约”这一理念有着强烈的响应机制——它会将每一行注释视作待实现的接口约束。举个例子：如果注释写明“// 输入：用户ID（非空字符串）”，模型就不会接受None或数值类型；如果注释写明“// 返回：成功时返回字典，包含code=0和data字段”，它就绝不会返回True/False或者列表结构。

不提供示例时，模型的默认行为是按照通用模板填充，生成的结果往往带有明显的“教学代码”痕迹：缺乏上下文的孤立函数、没有参数校验的直接调用、缺少关闭逻辑的资源操作——这些在真实项目中都会引发运行时异常。一句经验之谈：示例就是钳位信号，为模型提供清晰的边界定位。

三类注释示例写法与效果对比

方法一：单行内联注释（适合简单函数）

在函数参数行后紧跟//开头说明，每行定义一个语义单元。以日志行解析函数为例：

def parse_log_line(line: str) -> dict:
    // 输入：原始日志字符串，格式为"[2024-01-01 10:23:45] INFO user_login success"
    // 输出：解析后的字典，包含timestamp(str)、level(str)、event(str)
    // 异常：输入为空字符串时抛出ValueError

操作方式非常直观，直接将这三行注释粘贴在函数定义下方即可。模型看到后会严格依据注释生成函数体，连docstring都会自动补全——关键是输出结果的确定性大幅提升。

方法二：块注释+伪代码混合（适合逻辑分支较多的函数）

使用"""包裹说明，并在关键位置插入缩进的伪代码：

def calculate_discount(total: float, coupon: str) -> float:
    """
    根据订单总额与优惠券码计算最终折扣金额
    规则：
      - 满100减10：coupon == "DISC10"
      - 满200减30：coupon == "DISC30"
      - 其他情况不打折
      if total < 100:
        return 0
    """

这里有一个细节需要留意：伪代码中的if语句必须顶格书写，且不能使用中文冒号——否则模型容易误判为真实代码而跳过生成，最终导致打折逻辑全部缺失。

方法三：分段式接口注释（适合类或模块级生成）

先定义类骨架，再为每个方法单独添加注释块，最后用// TODO: 根据以上注释实现完整类收尾：

class DataProcessor:
    def __init__(self, source_path: str):
        // 初始化：加载source_path指向的CSV文件到内存
        // 要求：使用pandas.read_csv，设置encoding="utf-8"
    def filter_by_date(self, start: str, end: str) -> pd.DataFrame:
        // 过滤：保留date列在[start, end]闭区间内的行
        // 要求：date列为datetime64类型，自动转换
// TODO: 根据以上注释实现完整类

这种写法能够让DeepSeek生成带有完整类型注解、符合PEP 8规范的类，并且所有方法内部都会自动包含参数校验和类型断言——省去了手动编写样板代码的时间。

实操要点：让注释示例真正发挥作用

第一步，打开DeepSeek对话界面，确认已开启“深度思考”模式。第二步，粘贴带有注释示例的提示词，确保注释统一使用//或"""包裹，且没有中文标点混用的情况。第三步，在提示词末尾追加硬性约束——例如“所有函数必须包含完整类型注解”“每个异常路径必须有对应测试用例注释”“不得使用eval、exec等危险函数”。这样添加约束后，生成结果的稳定性会明显提升。

第四步，点击生成，等待输出完成。第五步，将生成的代码复制到编辑器，使用mypy + pytest快速验证类型与逻辑——如果报错，说明注释示例某处存在歧义，需要回溯修改。这套流程走下来，脚本生成的稳定性能得到显著改善。

请注意，注释示例不是让模型帮你写文档，而是为它提供一张准确的地图——它走偏的概率就会小得多。