夜雨聆风你有接手过别人的测试程序吗？打开文件，几千行代码。没有注释，没有文档。变量名是a、b、tmp。唯一能看懂的是几行英文提示语。想改一个参数，不知道这个参数在哪些地方被用过。想加一个测试项，不知道往哪里加。
这时候脑子里只有一个想法：重写。但是重写是不可能的。最终只能硬着头皮改，改完不知道有没有引入新问题。
这个场景并不陌生。测试程序的生命周期比大多数人想象的长——芯片不改版，程序就不会大改，但小修小补不断。一份程序可能被不同的人维护五年八年，如果注释和文档没跟上，每一任接手的人都在猜。
一、注释的价值
注释不是写给机器看的，机器不需要注释。注释是写给下一个维护程序的人看的。那个人可能是你的同事，也可能是半年后的你自己。
好的注释回答的不是“这段代码干了什么”，而是“这段代码为什么要这么干”。前者代码本身就能看出来，后者才是信息差所在。
举个例子来说，直接看代码可能知道“这里延时了10毫秒”，但为什么要延时10毫秒？是为了等电源稳定，还是等芯片内部复位完成，还是为了配合测试机的测量时序？这些信息在代码里看不到，需要注释来补充。
再比如某个寄存器写入了一个非常规的值，代码里只有一行“write_reg(0x2A, 0x05)”。没有注释的话，后来的人看到这行会疑惑，这个0x05为什么要写在0x2A地址上。如果注释写清楚“0x05是关闭PLL旁路，芯片勘误表里写明必须做这一步”，维护的人就不用去翻几十页的勘误文档。
二、哪些地方需要注释
不是所有代码都需要注释。自解释的代码不需要，关键的决策和背景需要。
以下几类情况建议加注释：
第一，非直观的数值或逻辑。比如前面提到的延时10毫秒、寄存器写入非常规值、特殊时序设置。这些东西看起来像是“随手写的”，实际上是有依据的。注释就是记录这个依据的地方。
第二，绕过问题的代码。量产测试中经常有这类代码：芯片本身有问题，但为了不耽误出货，在测试程序里做了特殊处理。比如某批次芯片读出值偏高，程序里减去一个修正值。如果这里不写注释，后来的人只会觉得这个修正莫名其妙，甚至可能删掉它。
第三，测试项之间的依赖关系。依赖关系管理的这种逻辑在代码里往往看不出来，只有通过注释才能让维护者知道“这个测试项必须在那个测试项之前执行”。
第四，测试条件和规格的出处。某个电压设为3.3V，这个数字是从芯片规格书里来的。某个判断限是客户要求的。如果注释里写明来源，将来规格变更时就知道该改哪里。
三、注释的写法
好的注释有一些共同点。
1、简洁。一句话能说清楚的事，不写三句话。注释太长没人看。
2、明确。不写“这里有点复杂”这种废话，直接说明“为什么复杂”“怎么处理的”。
3、一致。整份程序用同一种注释风格。要么全用中文，要么全用英文。要么每行都加注释，要么只在关键处加。风格统一了，读者不用花时间适应。
4、和代码同步。最可怕的注释是误导人的注释——代码已经改了，注释没改。过时的注释比没有注释更可怕，因为它会把你往错误的方向带。
四、文档的价值
注释解决的是代码内部的解释，文档解决的是宏观层面的信息。
测试程序至少需要两份文档：一份是程序说明，一份是版本记录。
程序说明讲清楚这份程序是干什么的。包括：对应哪颗芯片、什么封装、什么温度等级；使用哪款测试机台、哪个硬件配置；测试项有哪些、大致顺序是什么；怎么配置、怎么跑、怎么看结果。这些信息写在文档里，新人接手时不用从头读代码，先看文档就能了解大概。
版本记录记录程序的每一次变更。谁改的、什么时候改的、改了什么、为什么改。这些信息在追溯测试异常时非常关键——某一批良率突然变了，翻了版本记录发现是两周前改了某个参数导致的，马上就能定位方向。
五、现实中的窘境
写注释和文档需要时间。而测试工程师的时间从来都不够用。项目赶进度的时候，第一反应是“先跑通再说，注释后面补”。但后面基本不会补。
这是人之常情，也是问题所在。
比较好的做法是把注释当作测试程序开发的一部分，而不是附加任务。就像写代码时顺手把括号对齐一样，写注释也养成习惯。
注释可以很简短，几句话甚至几个字，只要能传达关键信息就行。真正耗时的是那种长篇大论的文档，但测试程序不需要写论文，把关键信息说清楚就够了。
测试程序的寿命比写它的人预期的长得多。你以为只用一次的东西，往往会用五年。五年里，人会换三拨，记性会模糊，唯一能传递信息的只有代码里的注释和旁边的文档。
代码写得好，只是解决了“现在能用”的问题。注释和文档写得好，才解决了“以后也能用”的问题。
下次改程序的时候，顺手写一行注释。不花多少时间，但几个月后的自己会感谢你。
我们设计了一套芯片测试工程师培训课程。
内容包含半导体测试基础、ATE 机台操作、晶圆测试流程、测试向量优化、失效分析等，适合零基础入门和岗位能力提升。
如果你想系统学习芯片测试技术，可以联系我们。
刘老师｜13166339996（微信同号）
