先说结论：注解必须写，除非 code 太过简单。
我不相信有“看得懂的命名”这东西。
哪怕是我现在全部写中文，发到网络上，
只要字数多到一个程度，就会有一堆人看不懂中文表达的意思。
更不用说是程式码。
连命名都看不懂，就更要花大量的时间去厘清整个 code 的逻辑才看得懂“写什么”。
看懂写什么之后，更重要的是看懂“为什么”这样写。
而注解，就是一个省下看得懂“写什么”跟“为什么”时间的好东西。
然而，会议跟文件是码农最大的敌人，
在某种程度上，注解也是。
所以注解，在精不在多，在关键不在详细。
注解和 code 是完全相依的，
如果注解既繁且杂没重点，那基本上 code 是垃圾的可能性很高。
善于写 code 的人，要锻练自己写注解的能力。
最好别人不用去 trace code，只要看一遍注解，就可以接手。
所以好的注解，可以引导别人的思路，就跟写小说一样。
－－－
这就又回到如何写 code 的命题，这里举个例，
每个人习惯不一样，所以姑且参考。
我个人很喜欢 if，但非常讨厌 else。
if 是可控的，else 不可控，思虑再慎密的人，都会败在 else。
透过许多可控的 if，逻辑一脉相承，注解写起来就非常轻松，
只要解释为什么我要用这些 if，跟这些 if 在做什么事。
也许 if 太多很难看，把许多 if 精简后变成短短几行看起来非常炫，
但对于要理解 code 的人来说，反而是要在大脑里把这短短几行，
拆开并还原成所有的 if 条件，再去逐一理解－－浪费时间又容易错。
把 if 归纳成 function 之后，对我来说没有什么功能是三个 block 无法说明的。
// if ..., do ...
case -> if -> handling
画成 block diagram 就是一个唬弄客户跟长官的好东西。
好吧这是题外话XD
也许写完这个功能要数百行 code，但注解可能就十几行。
解释一下“写什么”(do) 跟“为什么”(if) 就好。
如果注解写成这样
code .... code ... code ... // comment
在一行 code 后面还要注解这行在干什么，基本上就是一种失败，
因为这表示别人连这一行 code 都得靠注解才看得懂。
失败的不是注解，是 code 写太烂。