※ 引述《sec5566 (sec)》之铭言： : 以前上课跟书本都提到写注解， : 但是我看资深同事还有接手的程式码， : 都没有注解，只有我在写， : 还被主管念过写注解没必要， : 命名好就够了， : 是我观念落伍了吗？ : ----- : Sent from JPTT on my Sony H4331. 『写注解到底是不是好习惯？』 虽然这是一个老梗的题目，但不同时期都有不同的想法啊。 特别是工作多年後，可以站在不同角色来想以前没想过的事。 我有时候充当替新手导览的角色，每回接触不同的新手级工程师， 都是不同的文化冲击。 通常在『新手村』模式的基本要求就是『忠实』表达想法， 我需要明确地知道对方『懂』或『不懂』。 尽管试着装懂，那在接下去的对话也会很快地能诊对出 我眼前面对的初级工程师目前的思绪是卡在哪。 就会再次提醒，若不懂我说的概念，或眼前所见的程式无法理解的情况， 请立即提出。 对於初级工程师或者新进的工程师，对我们正在进行的专案是陌生的。 在我『诚实』的基本要求之下，我很可能有机会在这个 mentoring 的最初阶段一直听到『我看不懂程式』。 程式里面没有注解吗？有些地方有，有些地方没有， 但是这不是简地说说注解写得好或不好可以解决的。 因为注解并不是为了这样情境写的『要让第一次看这份 code 的人就懂』， 况且我们大部分的时候，不会在注解上花费太大的篇幅在写注解， 也不会有特别细琐的事写在上面，要理解一段程式， 要有一定的背景知识存在。 对我来说『注解』是程式的一部分，它能用来支持程式可执行单元的表达性。 若是程式可执行单元已经足够描述意图了， 那注解只是使用另一种语法再写一次说明罢了， 但事情并没有那麽单纯，因为每个人的理解并不完全一致。 文章里开头提到的『命名好就够了』， 现实上一定会有人觉得这命名懂，另一些人觉得这是 3 小朋友的情况。 这就是前面说的『背景知识』不一致产生的思考落差。 这现象并不是有没有写注解或命名好不好的问题。而是该有的背景知识缺乏， 而无法理解这个队团的思考惯性的问题。 简而言之，你还没有融入这个团队的工作模式： * 核心的系统隐喻 那些讨论过的 spec 内，有些核心的逻辑， 围绕这些逻辑的核心用语与动词。 这里的 spec 并不是只 SA/SD 那个时间产出的标准文件， 而是我们在讨论 issue 时，具体实现方法的主要概念与细节。 * 对针主要的工作产出有共通的视野 在讨论 spec 或 code review 时，渐渐塑造成共通的视野。 在互动的过程中，我们才能知道队友的想法是不是一致， 所以鼓励每个人表达是相当重要的，特别是刚加入团队的同事， 只要他默默地不说话，那就得制造机会给他。 或是偶尔小出槌制造一下别人反驳、纠正观点的机会。 因为只有在想法上有冲突时，印象才会深刻， 认知通过冲突调和之後形成的共通视野才会稳固。 * 统一的术语 在前 2 个过程中，我们还没有真的建立好核心隐喻 (一个名词 与 相应能适用的 动词 们) 可能会用很多不同的词来描述概念，最後我们只能保留其中一些， 作为最重要的术语。才不会让『概念』漂来漂去， 或让新进的参与者有其他联想。 程式码中可以执行的单元，或不可执行的单元 (注解或一些只存在编译期的语法结构) 是否具表达力是透过互动过程建构的。 我们得沟通、得聊天才知道想法有没有差距， 有了共通的文化小圈圈才能知道哪些 [命名 / 注解] 是容易让团队其他人看得懂的。 工程师的工作是一个互动的过程，它不像过去学校交作业，然後等待评分而已。 你得去跟你的同事互动，聊聊正在开发的程式， 多谈谈你的理解才好融入团队的思考惯性。 --

※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 36.231.138.44 ※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1546144956.A.439.html