2026答辩代码注释：函数头三行写法

答辩时老师翻到你的代码，指着一个函数问：“这段是干什么的？哪几行是你改的？”很多学生的反应是从函数开头逐行念代码，念到一半自己也乱了。问题不在口才，而在代码里没有一处能让你和老师同时看懂的说明。解决办法是给每个关键函数的头部固定写三行中文注释：输入是什么，输出或副作用是什么，本人改了哪里。

下面用一个贯穿例子讲：程序读光线传感器数值，判断是否低于阈值，低于就点亮小灯。代码均为示意伪代码，数字均为示意。

int readLight() {
    return analogRead(A0);       // 示意：返回0到1023
}

bool isDark(int light) {
    return light < 500;          // 示意：阈值500
}

void driveLed(bool on) {
    digitalWrite(13, on ? HIGH : LOW);   // 示意：13号口
}

三行注释用同一个模板

/*  @输入：...
 *  @输出/副作用：...
 *  @本人改动：...
 */

“输入”写函数接收的参数和含义，没有参数就写“无”。“输出/副作用”写返回值，或者它改变了哪个变量、哪个引脚的状态，两者都有就用分号隔开。“本人改动”写具体改了什么，整段自己写的就写“新建”。每行控制在二十来个字，写长了就说明这个函数做的事太多，可以考虑拆开。

同一个函数加注释前后对比

以isDark为例。教程原版的阈值写死为500，你把它改成了一个可以调的变量。加注释前，老师只能看到一行比较语句；加注释后是这样：

/*  @输入：light，0到1023的亮度值
 *  @输出/副作用：返回true表示暗，false表示亮
 *  @本人改动：固定阈值500改为变量darkLimit
 */
bool isDark(int light) {
    return light < darkLimit;    // 示意：默认500，现场光线强时调高
}

对比一下就能看出差别：函数体只多了一个变量名，但头部三行让人不读代码也知道它在做什么、你做了什么。函数体里的注释只留一句“为什么”，比如“现场光线强时调高”，而不是“返回比较结果”这种逐行翻译。

本人改动写行号或功能点

“本人改动”这一行最容易写空。“优化了代码”“做了修改”这类说法，老师一追问就答不上。可以用两种写法：

如果参考了教程或队友的代码，就照实写“基于教程示例改写”，再列出差异点。分清哪部分是自己做的，比假装全部原创更经得起追问。

答辩时指着注释讲30秒

注释写好后，讲解顺序就固定了：先输入，再输出，然后是本人改动。以isDark为例的示意讲稿：

“这个函数输入的是光线传感器读数，范围0到1023；输出是真或假，真表示环境暗。我的改动在这一行：教程里阈值写死500，我改成了变量darkLimit，因为在教室测试时窗边太亮，小灯一直不亮，改成变量后调试只要改一个数。”

这段话约30秒（示意），全程手指在注释上，不需要念代码。老师如果追问具体哪一行，再指向函数体里用到darkLimit的那一句。改动背后的原因，比如“窗边太亮”，是最能说明你真正动过手的部分，建议写进实验记录里，答辩时才说得出来。

不要把代码逐行翻成中文

有的同学在每一行后面都加中文，例如在analogRead后面写“读取模拟口”。这类注释没有增加信息，老师看代码本身就懂；答辩时把它们念一遍，反而显得抓不住重点。函数头三行讲清作用和改动，函数体内只在不显然的地方写原因，这样注释总量少，信息却更多。

今晚就能做的下一步

打开项目源码，把所有函数名抄到一张纸上。逐个按三行模板写输入、输出、本人改动；哪一个写不出来，就说明你还没弄清它在做什么，正好借这个机会重读。然后挑三个核心函数，把注释敲进代码，再对着屏幕按“输入—输出—改动”的顺序各讲一遍30秒，请家长计时。