你见过最离谱的代码注释是什么？我见过有人在@param后面写"那个数字"，三个月后他自己都看不懂什么意思。更夸张的是有同事在@return标注里写"你猜"，结果被项目经理当场抓包——别笑！今天要讲的这些标注技巧，能让你避开这些坑爹操作，顺便在公司混个"文档小能手"的称号

（敲黑板）先说个真实案例：上周实习生把参数说明写成"输入你要的东西"，测试小哥跑过来质问"我要的东西是钱你给吗？"。其实只要掌握下面这些标注规范，这种尴尬分分钟能避免

---

一、参数标注：别当谜语人

看到这个方法没？

java复制
/**
 * 计算商品价格
 * @param a 数量
 * @param b 单价
 */
public double calculate(double a, double b){
    return a * b;
}

??问题大了去了??！这a和b换成中文变量会死吗？改完应该是：

java复制
/**
 * 计算商品总价
 * @param quantity 购买数量（必须大于0）
 * @param unitPrice 商品单价（单位：元）
 */
public double calculateTotal(double quantity, double unitPrice){
    return quantity * unitPrice;
}

重点来了：@param后面??先写参数名，再解释业务含义??。就像点奶茶要说"少冰三分糖"，不说"按老规矩来"

---

二、返回值标注的三大禁忌

见过这种注释吗？

java复制
/**
 * @return 结果
 */

这和没说有啥区别？教你三招：

1. ??说明数据类型??：返回的是String还是int？
2. ??描述业务含义??：是订单ID还是错误码？
3. ??特殊值说明??：比如返回-1代表异常

改完的版本长这样：

java复制
/**
 * @return 用户年龄（0表示未获取到，负数代表数据异常）
 */
public int getUserAge(){
    //... 
}

不过要注意！别学某些人在注释里写"返回42代表宇宙真理"，这种冷笑话容易引发团队内战

---

三、表格对比：好注释 vs 烂注释

烂注释特征	好注释要点	真实案例改造
"输入数字"	说明数值单位	订单金额（单位：分）
"返回数据"	明确数据结构	返回JSON格式的用户信息
"参数你懂的"	标注必填/可选	收货地址（必填，最多50字符）
"异常返回"	定义错误码	返回-1表示网络超时

这张表建议截图保存，下次写注释前对照检查。我团队里有个哥们把它贴显示器边框上，现在他的代码评审通过率飙升

---

四、自问自答环节

Q：参数说明要详细到什么程度？
A：想象你在教新人——比如"userId要传数据库主键ID"比"用户ID"多了关键信息，但别写成"这是张小龙在2012年定的规范"

Q：方法有多个@param怎么排序？
按参数在方法中的出现顺序排！别学某些强迫症按字母顺序排，结果和代码实际参数顺序对不上

Q：返回值需要写示例吗？
复杂的结构可以写，比如：

java复制
/**
 * @return 类似{"code":200, "data":[...]} 
 */

但别把示例代码和真实逻辑搞混了，上次有人复制粘贴示例代码导致生产事故...

---

五、隐藏功能：让IDEA帮你检查

按住Ctrl键点击@param里的参数名，要是参数名和方法定义的不一致，IDEA会画波浪线警告！这个功能我愿称之为"防手残神器"

不过有个坑：如果你改了方法参数名但没改注释，IDEA也会报错。这时候别慌，按住Alt+Enter选"Update javadoc..."就能自动同步

---

（转椅子声）写完这篇突然想起刚入行时，带我的师傅说："代码是给人看的，顺便给机器执行"。现在看那些写得跟说明书似的注释，终于明白他的深意。最后说句得罪人的话：宁可写"@param username 登录用户名（最大16字符）"这种啰嗦注释，也别当留谜面的谜语人——毕竟咱们程序员头发已经不多，就别互相伤害了吧？