※ 引述《alihue (wanda wanda)》之铭言：
: 转自推特
: https://twitter.com/BenLesh/status/1372562839475470336?s=20
: Add comments about WHY code exists, not what it does.
: The code is right there, we know what it does.
: 注解应该用来解释这段 code 的背景需求/含意，
: 而不是把 code 表面上的意思再讲一次
上周在重构某段程式码时，其中一位同事在 code review 中建议把某个注解删掉，另一
个同事看到这个评论时，在下面留了言说他认为不应该删掉，于是我们就拉了一个小讨论
，聊在程式码中写注解这件事。
因为这个经验，我回去重翻史丹佛电脑科学教授 John Ousterhout 写的《A Philosophy
of Software Design》一书，并整理了笔记。该教授的观点是认为程式码写注解有很多好
处，但不是任何地方都该写注解。
在版上找到这篇之前有版大发的文，基本上跟 John Ousterhout 教授的观点一样，
就是注解要解释背后的“为什么”，而不是把程式码做的事重复说一次。

推~感谢分享

推 谢谢大大分享

好文推推

没时间看完整篇文章,这就跟一万小时变大师的观点呵呵

推

推 我注解都看心情 然后画恐龙注解图 嘻嘻

讲的好

推分享~注解本来就该写这段在做啥,为啥这样做

推～上次看这本书好久以前了 看完心得整理好像又读一遍了

我想要知道函式的功能 和为什么要用无符号整数来存指标QQ

推，meta data那段讲的不错

分享推

感谢分享～

那需求一直变，后续也要持续维护这段注解吗？

我记忆力很差 我的注解都是为了让以后维护的我看得懂这段code在写啥

楼上的状况我也有,只是我都用git取代注解就是了

回 aid：我自己会注解加说是什么时候的需求、修改的新逻辑是什么，程式注解我都会维护

注解是需要维护的，但注解只是辅助工具，理论上不会多到造成负担，如果会，可能是程式太乱需要大量注解，或是有太多没必要的注解

我注解只会写特殊的商业逻辑来辅助程式码的不足~

推楼上

当文件的一环吧文件要维护，注解当然也要

优文推一个，谢谢分享

注解当然要维护啊，但至少没维护历史看得出来

感谢回复，之前看clean code提到很多写注解的坏处，像是接手的人不一定会维护注解、注解缺少维护可能会过时、误导等坏处，后来只有TODO我才会写注解，宁可后人多跟PM确认新的现状不然注解写出来，也不太有人敢修改、删除可能也是个问题

没写注解基本上也不应该随意修改删除啊，要做的事情是补测试或是找人厘清需求，再去做变动，注解就是辅助工程师更好做到这些事很多人不写注解或是不喜欢文件以及测试的理由都是要多维护的工，但往往省略掉这些以后，是花更多的时间开会，或是慢慢变技术债

“不一定会维护“这为啥要算注解的缺点....整个软件开发一堆东西都有人不维护= =

另外需求一直变并不是不写注解的理由，不写就是用人脑记忆，没纪录还可能记错，基本上就是赌这个未爆弹不会炸到你而已

修改删除是指注解，因为不及时更新注解就会随需求变动过时，可能造成误导而非指引

这本书作者的论点跟 foreverk 大说的蛮相近的这位史丹佛教授在书中最开始就提到，他不认同蛮多Clean Code 里面提到的观点，但他也不觉得自己的就适合在所有脉络。所以他的书名是 a philosophy而不是 the philosophy

如果指得是不敢修改或删除注解，那就代表改code的人并没有完全掌握这项功能，改善方式应该是增加掌握度，而不是舍弃注解本身

推

假如有好好写 commit 讯息，再写个简单 script 可以过滤时间/档案/行数/关键字/作者 找出相关 commit 也不错

好的程式不需要注解，你说得都是文件应该要做到的

推

不写注解很常伴随着不写文件，最常见的第二个理由就是认为好程式不需要注解/文件，可是一些特殊商业逻辑所产生的程式，他不好但他是因应当时时空背景而生，这类情况还不写，那就是上面我说的未爆弹楼上说的commit也是应该要好好写的一点，甚至应该pr也好好写，不想维护一整份文件的话，更应该从这些细节去提升程式可维护性

写注解这种事就是谁当老板就听谁的...现实世界就是阶级,书再怎么卖学校再有名都没用

如果有些重构会搬移程式码到不同的专案或档案这时git的纪录也很难追踨

一个方式是搬家时旧的留着标 deprecated, see also...留个线索给人查

不认同 为什么不是精简化实现而是把有复杂度的东西藏起来 这团code怎么乱七八糟都没差反正有注解？ 现在一堆东西坑很多就是这样来的 包含框架甚至语言底层本身如果你不去仔细研究也会被坑到写程式有两种方式 一种是把程式写的很简单 明显不容易有缺陷 一种是写的很复杂 让别人看不出有明显的缺陷依照这样搞你边写没写可以模糊焦点的注解 还可以边藏bug和洞

有没有可能一段程式复杂到需要注解的时候就是应该再拆分它然后把功能单一化的时候?

我的经验是，通常不是程式复杂到需要注解，而是因应特殊需求而出现的程式需要，他可能写死很多地方，程式风格明显不符，或根本是粪code，但暂时需要

我们非英语系国家 不然解法就是在method名称上取一个好一点的名称让大家所见即所得 然后一个method尽量只做一件事但一堆人英文不好ABC狗嘎D method名称乱取一通

好文，推注解是要说明为什么，而不是干什么

有一种状况就是我不知道为什么，所以我写了它干什么...

// ［MOLYXXXXXX]

复杂和不复杂还是不复杂好多了 复杂本身也会掩盖程式真实的目的 学着用本身是种痛苦不说 学到的东西也是皮毛 也没什么高深的哲学用来提升自己 就是硬塑造的技术壁垒不复杂就容易追踪程式码 再差也差不过一堆你不爬文就不知道怎么回事的东西

写code一样注解新手满容易犯，Review别人code有助进步

推

感谢分享～

推

注解不写…，那其实等于没写过什么重要的东西。所以才养成不写注解

当你觉得这段 code 未来会有人来问你为什么这样写时，就代表该留点注解了

推

推楼楼上

重要的东西照样不写 要写其实文档好过注解就现况来看清晰好了解的注解根本没有 因为人人都不爱写 都是叫别人写颐指气使自己要写堆三阻四 给人制造障碍要看那堆垃圾注解 不如程式本身简单质量好看到最后还是自己分析程式比较快

注解优于文件的点在于修改出出程式时可以一并集中修改，不需要大老远去找文件出来改。另一方面，在不愿写注解的情境下，更不可能愿意去翻找并维护离程式码更遥远的文件。除非在包含系统整体设计与脉络时，另外管理的文件才会展现出优势

注解是分散的 你改一个以为相关的不用改？文档具有统一性更好些 大专案重要的是整体架构注解表达的是片面的 只是讲述区块的程式你也不可能逐字讲解 本身表达力就不足至于找文件...一个quick open快捷键就打开了好吗 还可以内文检索如果会vi/vim那就更强了

我想两个都有是比较理想的情况，虽然实际情况很常两个都没有

没什么好说的 从来没有删掉注解的除非注解写错了