先说结论：注解必须写，除非 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 写太烂。 -- ps1. 我年轻时喜欢弄一堆漂亮的 block diagram， 什麽 function flow, data flow 的， 现在我认为那都是屎。 程式架构应该是只要一张表格加上代码本身自带的注解就足够让人了解了。 -- ps2. 我绝对没有在婊 Linux kernel 架构图的意思， 毕竟好的架构图绝对是有助於了解整体程式码结构的。 -- ps3. 写 comment 的时候，把对象想像成一只猴子有益无害。 -- ps4. 这篇写到後来本来觉得烦想删掉， 但想想辛苦写了这麽久，还是赚个p币好了。 --

※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 59.127.94.119 ※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1546008917.A.C92.html 可惜随着功能愈来愈强大，程式码自然就愈趋复杂。 把复杂的 module，拆分成独立 tiny module，每个 module 都变得精简， 这样增加了可读性、重复利用性、可维护性，是工程师该做的。 但其实没有把 code 变得简单，只是把一个 function 能做的事， 变成一堆 function 合起来作。 当我一个 function 里面 call 了 100 个其它的 function； 或者 function flow 拉得很长，跨越了 100 个 function。 也许我每个 function 都通俗易懂一目了然，不用注解， 但还是得花时间看完这些 code 才懂这 100 个 function 合起来是在干嘛。 而这个时间，也许只要两行注解就可以代替。 想像一个具有 100 个 event 的 event sysem， event 间另有交互合作及互斥关系， 也许每一个 event 都只用了两三行 code，一看就明白， 所以不需要注解这个 event 在干嘛。 但其它的人，光是要找到其中一个 event 就很花时间， 更不用说这个 event 牵涉到其它的哪些 event。 function event1_handler() { code line 1... code line 2... } 这样超简单的 event，不用注解吗？ 我觉得要，注解可能会长这样 // event 1 affects // - event 22 // - event 36 // - event 47 // - ... // and NOT used concurrently with // - event 7 // - event 71 但类似这种注解会需要花很多时间维护， 所以我个人会建议记录成一张表格就好。 ※ 编辑: babelism (59.127.94.119), 12/29/2018 11:20:08