※ 引述《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 教授的观点一样， 就是注解要解释背後的「为什麽」，而不是把程式码做的事重复说一次。 ------ (以下是我读完该章节後整理的笔记) ------ ## 网志好读版： http://bit.ly/3WdTo1b 每当提到在程式中写注解 (comments)，你大概会在网路上看到两派人马，有人觉得应该 要写注解；又有另一群人觉得程式码应该要写得够清楚，如果有注解就代表写不够清楚， 应该要重构而不是加注解。当然除了这极端的两派人马外，多数人都是在中间，部分的程 式码写注解，但不会全部都写。 关於写注解这件事，在 《A Philosophy of Software Design》 书当中也有谈及。John Ousterhout 教授的观点是，如果注解写得好，将有效改善整体的系统设计。假如你是反 注解派的人，或许可以一起来读读他为什麽这麽认为。 ## 程式本身写得够清楚，就不用注解吗? 「程式本写得够清楚，就不用注解」是很多人认为不该写注解的第一大理由。然而程式本 身或许可以清楚表达该程式码做的事，但不能解释「为什麽」要这样写，也不能解释在什 麽情境可能比较适合某个方法。对於这些相对後设 (meta) 的内容，注解就是很好的帮手 。 更进一步说，好的软体设计，应该要把复杂度藏起来，要藏起复杂度，我们需要抽象化， 让其他使用该段程式码的开发者，可以不用去管背後的细节。因此，如果一个开发者，还 要去读程式的细节才能懂如何用该函式或方法，那就失去抽象化的意义。写注解可以让其 他开发者，不用去读程式里头的细节也知道如何用该函式或方法，这才能达到抽象化的意 义。因此不论程式本身写的清楚与否，好的抽象化搭配好的注解，都是对整个程式库的维 护有帮助的。 ## 别说你没时间写注解 在开发时，很多开发者会认为写注解的优先顺序比较低，因此会想把时间花在写新功能， 而不是为已经开发好的功能写注解。然而在软体开发中，永远有写不完的功能，如过说因 为要开发新功能而没时间写注解，就永远不会有注解。从长远的角度来看，这样的代价是 程式库的可维护性会降低。如果从效益与成本的角度来看，写注解的时间，会远比其他开 发者花在弄懂没注解的程式所花的时间要少很多。 ## 不要找其他不写注解的理由 很多开发者也会找其他理由不写注解。例如认为注解如果没随着程式更新，反而会误导人 ；或者是因为过去读过别人写的注解觉得没用，就认为注解没有用。这些都是外部因素， 无法证成注解本身没有效益。此外这些都是可以透过好的流程而解决的，所以作者认为不 要找这些理由不写注解，而是要去打造更好的流程来改善这些问题。 ## 写注解的好处 上面谈了这麽多，大概可以看出 John Ousterhout 教授有强烈的观点认为要写注解。不 过回过头来说，写注解有什麽好处呢? 他认为最大的好处在於注解可以捕捉到程式码没办 法传达的资讯，这能够让未来要维护这段程式码的开发者，能够更快速地上手。特别对於 团队中加入的新成员，程式码中的注解可以大幅降低读程式的认知负担 (cognitive load)，以及减少未知。 如果没有记录下这些脉络与原因，未来的开发者就不会知道为什麽当初是这样写，这变得 只能猜测原作者的意图。这不仅更耗时，也可能会因为理解错原本的意图，导致在维护该 段程式码时出错。很多时候，未来要维护程式码的是自己，许多人在写完某段程式码几个 月後，可能忘了自己当初为什麽这样写，所以写注解不仅是帮助其他开发者，也很可能是 在帮助未来的自己。 ## 注解该写什麽? 虽说 John Ousterhout 教授的观点是认为写注解对软体设计有帮助，但他也同意不是什 麽都该写成注解。他认为只有在程式码中不显而易见的才该写注解 (comments should describe things that aren’t obvious from the code)。 在软体设计中最重要的抽象化，即是提供一个更简易的思考方式，让开发者可以不用深入 过於细节的部分。即使开发者可以透过细读程式码来了解其如何运作，但这样做太花时间 。John Ousterhout 教授的观点认为开发者应该要不读程式码内容，即可理解模组提供的 抽象化，而注解是能够协助做到这样的方法。 ## 不要重复程式码本身 前面提到，注解应该要讲「为什麽」这样写，而不是讲程式码在做什麽。毕竟程式码本身 就代表程式码在做的事，如果注解在写一次，会是多此一举。下面是书中提到的负面教材 ，基本上注解就是把程式码做的事情。 ptr_copy = get_copy(obj) # Get pointer copy if is_unlocked(ptr_copy): # Is obj free? return obj # return current obj if is_copy(ptr_copy): # Already a copy? return obj # return obj thread_id = get_thread_id(ptr_copy) if thread_id == ctx.thread_id: # Locked by current ctx return ptr_copy # Return copy 要怎麽判断你写的这段注解是不是跟程式码本身一样? 书中提到，在你写完注解後可以问 问自己「如果某个之前没读过这段程式码的人，能不能看着这段注解写出程式码?」如果 可以的话，就代表注解只是在描述程式码，而不是在解释为什麽这样写该段程式码。因此 ，在写完注解後，可以再比对一下程式码与注解，如果重复就真的不推荐写。 ## 从读者的角度出发 最後 John Ousterhout 教授提到，写注解要从程式码读者的角度出发，要思考有哪些关 键资讯是读者不知道的。特别是在程式码审查 (code review) 时，如果你写的某段程式 码让别人说很难懂，或者某个资讯让别人说并不显而易见，这时候不要去跟对方争，而是 去想为什麽对方会有困惑，以及你可以如何靠注解让程式码更好被理解。 (文末备注：这个章节本身有很多范例，但为了避免笔记变太长，就仅有放其中一个。有 兴趣透过案例更具体了解作者的观点的话，推荐直接买这本书来读)。 -- 南漂一不小心漂到了新加坡 https://www.explainthis.io/zh-hant/singapore --

※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 116.86.64.199 (新加坡) ※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1673785027.A.36D.html