代码注释的提示是怎么写的？过程拆开看

2026-10-18 发布来源：我告诉你AI导航阅读

用 DeepSeek 生成一段数据处理函数，代码质量不错，注释却要么一行都没有，要么每行都是废话。问题多半出在提示里没说清注释这件事本身——写给谁看、写多细、写在哪，都得先交代。

注释提示要先说清读者是谁

注释给刚入职的新人看，就要多解释业务背景；给熟悉的同事看，只需标注关键拐点；给未来的自己看，重点在「当时为什么这么做」。读者不同，密度和用词完全不同，一句话讲清读者，比写十条注释规则都管用。

注释密度怎么提

按块提：函数级注释写用途、入参、返回，行级注释只标非直观逻辑。
给反例：「不要逐行翻译代码」这句要写明，否则模型容易解说成流水账。
给比例感：「大约每十行有一处注释」比「适量注释」可执行。

分层注释的写法

复杂模块可以分两层：模块头部一段概述，讲清整体思路和数据流向；函数体内散点注释，只解释容易误解的行。通义千问对这种分层要求的遵循度不错，前提是两层的要求分开写，别揉成一句「写好注释」。

两层各写什么、各自排除什么，放在一起看：

注释层级	写什么	不写什么
模块头部	一段概述，讲清整体思路与数据流向	逐行翻译代码
函数级	用途、入参、返回	同义复述，比如给自增标一句「计数加一」
行级	只标非直观逻辑、容易误解的行	解说成流水账

注释效果的核对方法

遮码测试：只看注释能否还原代码意图。
抽查拐点：分支、异常、魔法数字处有没有注释。
查废话：把注释里「循环遍历列表」这类同义反复删掉。

长输出场景的行数管理见长列表输出的稳定性是怎么保的？；表格化输出的表头约定见表格输出的列名是怎么锁定的？内部门道在这；提示设计与任务拆解的通法见翻译任务的提示是怎么设计的？关键步骤一次讲清；要点提炼类任务见摘要任务的要点与长度控制？从原理到落地。

注释提示还有一个高频翻车点：模型把注释写成代码的同义复述，比如给自增一行标注「计数加一」，这类注释零信息量，根因是提示里没给好注释的样本。放一小段理想注释的节选进提示，比十条规则都直观，样本别取自本函数，避免模型直接照抄，取同项目其他模块最合适。注释语言与代码语言也要声明——中文注释配英文代码是常见组合，不写明就容易中英混杂。老代码补注释是另一个场景：让模型先读代码输出疑问清单，你回答后再让它写注释，带着答案写出来的注释才有业务味道。密度的黄金检验法还是遮码测试：把代码遮住只读注释，能还原八成意图就算合格，还原不了说明注释在复述而不是解释。禁用清单也值得写进提示，把「简单来说」「如上所述」这类废话开头列进黑名单，废话能少一大截。

注释提示三要素
读者：写给谁，一句话定调。
密度：哪一层写、写到多细。
反例：明确不要什么。
注释是写给人的路标，提示里把「人」说清，路标才立得准。

注释规范本身也值得写成项目文档：密度、语言、禁用句式、好样本，一页纸说清，提示里只需引用「按项目注释规范执行」并附规范全文，规范一页纸、提示一段话，比每次现场发挥省心得多。规范更新时同步检查提示里的样本是否过时，样本与规范打架是常见的隐性坑；检查频率跟着代码评审走，评审一次核一次，打架时以规范为准，当场修正样本，别拖到下一次评审。