前言
（注意，这篇帖子不是软件开发与创新的作业帖。）
上一期我们讲了萌新后端和老鸟后端的对比。
有观众说了：
“你连着说了好多遍‘代码即文档’的坑，我知道反例，但有正面例子吗？”
今天就趁这个机会讲一下：
一篇好的代码，不论谁写出来的，是如何做到不需要文档也能被看懂的。
第一部分：什么叫“代码即文档”（给没看过上期的补课）
还是上期的老话，正所谓“好代码千篇一律，烂代码各有千秋”，一份好的代码要满足以下条件：
- 变量名有实际含义
- 结构简洁，基本没有冗余代码
- 异常处理完善，健壮性要足够
- 关键的复杂点有注释兜底
才能够最大限度保证代码的可读性。
第二部分：萌新写出的烂代码陷阱合集（什么不该做）
陷阱1：变量名abc，图方便
场景：萌新写代码时，int a，long b，float c满天飞，觉得变量名用一个字母特别方便。
结果：团队项目自不必多说，老鸟或者PM在Review你代码时，才看了10行就已经想吐了，直接一手打回重做；个人项目没人管的话，萌新3天后再看自己的代码……
完喽。天书。（这张图片对应的文学作品真就是《天书》。）
老鸟内心：你当初写着是方便，但你有考虑过，未来你自己或者别人看你代码的时候是怎么想的吗？损人不利己的事建议少干。
陷阱2：不搞缩进，统一靠左
场景：萌新写多层分支/循环时，嫌敲TAB键太麻烦，也嫌编译器自动缩进“没个性”，索性全都靠左对齐。
结果：同上，甚至程度更加狠。要是你拿Python写，语法检查都不给你过去。
老鸟内心：你跟上面那位凑齐卧龙凤雏了是吧？！打回！重做！
陷阱3：goto及其同党
场景：萌新想着goto这玩意看都看了，不能白看，于是代码拼命写goto。
结果：前后端一时爽，测试火葬场。迪杰斯特拉早在1968年就写过一篇论文，标题为《goto有害论》（原标题：Goto Statement Considerred Harmful）。学术界喷这玩意都快一甲子了，甚至大多数编程语言压根不带这玩意。然而总得防着点有人拿C做后端……
老鸟内心：迪杰斯特拉早在1968年就写论文吐槽这玩意了，怎么滴？你比迪杰斯特拉还牛？你怎么不去拿个搞笑图灵奖呢？？哪个杀千刀的敢写goto，你跟我玩“翻来覆去”，我跟你玩“闪电快打”！
陷阱4：超大类/函数，啥都往里塞
场景：萌新写一个类成千上万行，一个函数几百行，美其名曰“高内聚低耦合”。
结果：审查的人此时已经额头青筋暴起了，毕竟这就好比你把所有鸡蛋全给放在一个篮子里，模块化程度是0.
老鸟内心：要不你干脆把事情做绝一点，直接全写main里头，全是内聚，没有耦合。
陷阱5：深层嵌套，俄罗斯套娃
场景：萌新写代码，if里面套if，if里面再套if，for里面套while，while里面套switch……
结果：萌新+审查+ai，没一个看得明白这份代码的。
老鸟内心：流程图都没理清楚，编什么代码？你家俄罗斯套娃套几百层的？！
陷阱6：魔法数字
场景：萌新代码里直接写if (mode == 3)、sleep(86400)，没人知道3代表什么、86400是什么。
结果：审查的人看着那个86400，陷入了沉思……
老鸟内心：你代码里的魔法数字比霍格沃茨还多，斯莱特林的学生都没你这么狡猾！
陷阱7：不写日志，不留痕迹
场景：队友发现问题问萌新，萌新由于没打日志，直接说“我觉得应该是XXX”。
结果：排查了114514小时，结果还没查到问题在哪行。
老鸟内心：你当你是武侠小说主角？还“万花丛中过，片叶不沾身”呢？？
陷阱8：注释比代码还难看懂
场景：萌新的注释写了，但写得莫名其妙
i++； // 把i加1（废话注释）
// 这里不能动，动了会崩（说了等于没说）
i=1 // 今天是个好日子（注释和代码完全对不上）
结果：老鸟读你的代码已经够难了，读注释还要再加一道破译工序。
老鸟内心：注释能帮人，也能害人。我能帮你，也能揍你。
第三部分：代码编写铁律（什么该做）
铁律1：命名要见名知意
- a、b、c → 滚
- currentID、orderStatus → 留下
- 只要别写abc，哪怕你英语比较烂，拼音也能接受
铁律2：缩进要统一
- 不用纠结空格还是TAB，但必须统一
- 行业内经常批判空格和TAB来回换的
- IDE自动格式化是神功能，别关
铁律3：函数不超过50行
- 一眼能看完的代码才不容易藏bug
- 超过50行 → 拆
铁律4：嵌套不超过3层
- 3层以上 → 大脑栈溢出
- 拆函数、早返回
铁律5：注释写“为什么”，不是“是什么”
- 代码说“是什么”，注释说“为什么这么写”
i++;
// 把i加1 → 废话
// 这里跳过第3种状态，因为…… → 有用
铁律6：日志要让人看懂
- 不是给你自己看的，是给半夜被叫起来的倒霉蛋同事看的
- 日志四件套：时间、请求ID、关键参数、错误码
第四部分：老鸟内心精选（代码风格受害者版）
萌新：“代码能跑不就行了？”
老鸟内心：
能跑。你跑完我重构。逸一时，误一世。
萌新：“我写a、b、c我自己看得懂啊。”
老鸟内心：
那这代码是你一个人维护？你写遗嘱呢？只给自己看？
萌新：“缩进太麻烦了。”
老鸟内心：
TAB键是贴纸吗？你按一下会少块肉？
萌新：“goto为什么不能用？C语言都支持。”
老鸟内心：
你先去看看，除了C之外，还有什么编程语言支持goto.
再者C还支持setjmp.h呢。你怎么不把整个系统写成状态机？
支持≠推荐，能写≠该写。
萌新：“这个魔法数字3什么意思？我忘了。”
老鸟内心：
你写的你问我？你是来写代码的还是来寻衅滋事的？
第五部分：总结
| 陷阱 | 症状 | 老鸟反应 |
|---|---|---|
| 1 | 变量名abc | 天书，打回 |
| 2 | 不缩进 | 卧龙凤雏，打回 |
| 3 | goto | 闪电快打 |
| 4 | 超大类/函数 | 全写main得了 |
| 5 | 深层嵌套 | 俄罗斯套娃 |
| 6 | 魔法数字 | 霍格沃茨毕业 |
| 7 | 不写日志 | 万花丛中过 |
| 8 | 垃圾注释 | 我能帮你也能揍你 |
最后一句人话：
代码这种东西，机器看没看懂不重要，反正有编译器解释器。
问题是得让人看懂。你写a、b、c的时候，但凡想过一次“别人能不能看懂”，就已经是老鸟阶段了。
键盘在你手里，你命由你不由天。
你写得像天书，审查的就让你重写。
你写得像个人，大家都轻松，何乐而不为？？
附：第八期自测题
问自己三个问题，有一个“否”你就还是萌新程序员：
- 你的代码不开IDE，用记事本打开能看懂吗？
- 你的注释写了“为什么”，还是只写了“是什么”？
- 你敢把你三个月前的代码拿出来看吗？
三个“是”才及格。少一个，立刻打回。