作者AmosYang (泛用人型编码器)
看板Soft_Job
标题Re: [请益] 写注解到底是不是好习惯
时间Sun Dec 30 17:52:48 2018
先说结论：「二分法命题比较有得战、比较热闹；若像下面这样去考量各种层面的
话，会很无聊 XD 。」
# 从 电脑科学 的角度来看
所谓「写程式」的「写」，在抽象意义上即是「表达(express)」 ；每种实用的语
言多半有其强项与短处，也就是方便与不方便的用途。
例如说，用 程式语言 来表达计算(computation)过程 ，尤其是表达给电脑看的计
算指令，通常来说会比用 自然语言 来得方便。
用 自然语言 (配合科学/数学符号) 来描述、解释问题，尤其是表达给人脑看的脉
络上下文(context) ，通常来说会比用 程式语言 来得方便。
是故，如果一个问题(problem) 是简单(simple)到可以从其
计算解决方案(solution)去反推出问题的全貌，那麽，的确用程式语言去描述计算
过程就可以了，也就是「不太需要去写注解」。
反之，如果一个问题的复杂度高，或其脉络是难以用程式语言去描述的，那麽，就
可以用自然语言这个更适合的工具，去描述该问题的脉络，也就是「有写注解的价
值」。
有兴趣的话，可以参考 DSL/GPL 的观念:
*
https://en.wikipedia.org/wiki/Domain-specific_language
*
https://en.wikipedia.org/wiki/General-purpose_language
# 从 软体工程 的角度来看
前面板友 ThxThx 在推文 [1] 里点出的文章，有更深入完整地探讨这个方向。
*
http://antirez.com/news/124
*
https://www.reddit.com/9m6ahs
Hacker News 上也讨论过 antirez 的那篇文。
*
https://news.ycombinator.com/item?id=18157047
[1]:
https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1546056944.A.99E.html
以下是对原文的摘要，加上简略的、我的解读与看法；作者 antirez 把注解分为
9 大类如下，且主张：「前 6 大类是相对有正面价值的，後 3 大类则有疑虑
。」
> * Function comments
「函式注解」，可以想成「介面(interface), API 」注解。
> * Design comments
设计蓝图、大方向的注解。
> * Why comments
相对於描述「如何(how)」的程式码 ，解释「意图、原因」的注解。
> * Teacher comments
深入解释「问题的脉络/领域(domain)」的注解 ，例如，某数学公式的由来
。
> * Checklist comments
列出「提醒/警示」的清单注解 ，例如，帮助後人避免踩中技术细节的地雷。
> * Guide comments
「导读」注解。
> * Trivial comments
解释「不言自明」之事的注解；读这类注解所需要花的精神，不见得比直接读程式码
来得少，且不见得能帮助读者更了解此程式要解决的问题。
> * Debt comments
技术债注解；或许应该以 issue/bug 的方式记录技术债，而不是藏在程式码
里。
> * Backup comments
以 备份 为目的，把旧的程式码以注解的方式留在程式码档案里。
易言之，不同型式的注解有不同的用途与价值。
# 从 人体工程 的角度来看
相对於 软体工程 ， 人体工程 XD 是更困难的。
真正的问题通常不是技术问题，而是认知、环境、历史等脉络上的问题，尤其是那
些「没有被说出来 / 没有便利的共同语言去表达」 的东西。
那些东西对轻重缓急的取舍拿捏有极显着的影响与冲击，却又常常是无影无形难以
捕捉、表达、沟通。
(「人体工程」离原主题太远了，就此打住。)
[编辑补充] 就「人体工程」这个题目，可以参考 qrtt1 写的这篇:
https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1546144956.A.439.html
# 结论
扁平化、二分法命题比较有得战、比较热闹；若像上面这样去考量各种层面、脉络
的话，会很无聊，很难战 XD 。
--
个人 杂谈、学习、英语、软体
https://www.facebook.com/tw.yang.30 https://www.facebook.com/30abysses/
https://twitter.com/twy30 http://www.30abysses.com/
--
※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 136.56.102.149
※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1546163575.A.4C5.html
1F：推 oneheat: 你这个太无聊了，应该没几个人会回 12/30 17:54
XD
※ 编辑: AmosYang (136.56.102.149), 12/30/2018 17:57:44
※ 编辑: AmosYang (136.56.102.149), 12/30/2018 17:59:12
2F：推 t64141: 光第一句就该推了XD 12/30 17:58
此串开头原po在解 天才小钓手 的成就 XD
※ 编辑: AmosYang (136.56.102.149), 12/30/2018 18:05:13
3F：推 t64141: 看完，再推一次 12/30 18:02
4F：→ pttworld: 注解分类是有意义的，讨论串某些推文明显和内文不同类 12/30 18:07
5F：→ yougigun: end 12/30 18:16
6F：推 landlord: 言之有物，推！ 12/30 18:17
7F：推 jaspreme206: 推 12/30 18:18
8F：推 nelley: 推这篇 12/30 18:51
9F：推 v86861062: :) 12/30 19:02
[编辑补充] 就「人体工程」这个题目，可以参考 qrtt1 写的这篇:
https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1546144956.A.439.html
※ 编辑: AmosYang (136.56.102.149), 12/30/2018 19:18:37
10F：→ qrtt1: 用人体有色色的感觉 12/30 19:47
11F：推 babelism: 九类注解很值得借监,和我的观点重合处甚多 12/30 22:35
12F：推 sa074463: 推 12/30 23:00
13F：推 rollr: 水准太高 12/31 01:39
14F：推 Ghamu: 事实上就有好的有不好 应该的 不应该的注解这样 12/31 02:11
15F：→ Ghamu: 但一堆真的都拿烂注解来说该写注解好棒棒 真的不敢恭维 12/31 02:13
16F：推 kyrie77: 推这篇 12/31 02:53
17F：推 freepenguin: 推 12/31 11:33
18F：推 Ouranos: 推推~ 12/31 13:40
19F：推 pttuser2266: 原本很好战的主题，不要打扰我我看戏 12/31 14:13
20F：推 ppc: 推个 12/31 14:40
21F：推 vn509942: 感谢大大整理分享 01/01 10:49
22F：推 agra: 这个切分分类视角很不错，有看有推！ 01/01 14:13
23F：推 polola6212: 这串下来只有这篇有营养........ 01/03 01:39
24F：推 crow1270: 推 01/03 19:09
25F：推 leicheong: Warning comments: 当你在用第三方程式库有gotcha 01/04 21:11
26F：→ leicheong: 例如statement需要特定顺序执行或者有bug而需要 01/04 21:11
27F：→ leicheong: workaround, 而说明文件没标示 (例如微软去年公布必须 01/04 21:13
28F：→ leicheong: 开启SMB1才能正常运作的软体清单... 很多人一直都没 01/04 21:14
29F：→ leicheong: 想到SMB1居然会被更新停用, 而且没几个人会知道在用 01/04 21:15
30F：→ leicheong: 的lib的技术细节吧)这些一定得下注解 01/04 21:16
31F：→ rocwild: 简单说就是看写什麽样的注解吧。比如说“问题(problem) 01/05 11:41
32F：→ rocwild: ”也是一种注解。 01/05 11:41