《程式英文》 https://github.com/EngTW/English-for-Programmers 上周跨过了 「GitHub 500 星」的里程碑，在此整理一下这 12 周以来的心得。 * 讨论了 64 个与程式写作有关的英文字 * 每周新主题的热门程度不一，点阅人次分布在 3000 ~ 5000 * 每周流量有大约 10% 是重访既有主题 --- * Google 文件 https://bit.ly/2GvWwV2 * GitHub 讨论区 https://bit.ly/321ResR --- # 「命名」这个问题的本质 写程式时，「好的命名」的作用可说是： * 以精练的文字引导程式码读者的大脑聚焦在最重要的相关知识与经验上 * 进而掌握程式码的 How & Why 「好的命名」很重要，但「命名得好」很难，我将「命名的难处」归纳如下： * 缺乏学习诱因 * 就「写程式的当下」来说，最低限度的要求／短期报酬最高的目标，可说是「 写出能用的程式」。 * 而「可读性／好的命名」的短期报酬相对地低。 * 缺乏练习环境 * 就「语法、逻辑」来说，取得意见回馈很容易；可以用程式语言工具检查语法 ，可以演算验证逻辑。 * 而「可读性／命名」的品质评监是相对地困难。 * 缺乏技术指导 * 在这个时代可以找到许多「命名常规(convention)」的资料，是很有用的「语 法(syntax)、格式(format)」参考资料；同时，也有相当的资料在探讨「命名 的原则」及讨论「命名案例」。 * 而「命名的语意(semantics)」的资料相对地少。 --- 那麽，要如何克服上述的难处？我的看法如下： ## 学习诱因 诱因(incentive)、动机(motivation)是个很大的题目，这里先谈个人容易着手的 方向：「管理工作记忆区、调节情绪」，也就是降低「问题的复杂度、觉得困难的 情绪」对动机的负面影响。 易言之，如果目前无法做到「一次写出能用又好读的程式」，试试分成「写出能用 的程式」、「写出好读的程式」两个步骤来做。 可以参考 Test-Driven Development (TDD) 工程方法的原则，先写出「能用、好 掌握、好测试的程式」，再来改善程式的可读性（後面会探讨实作方法）。 另一方面，「团队文化、报酬制度」是个人相对难着力的方向，因为那通常不是技 术问题，而是商业问题。 ## 练习环境 这个时代有不少「语法检查工具」，但几乎没有「语意检查工具」；目前我能想到 的替代品有三： * Pair Programming * Code Review * 社群讨论 * 例如这一系列文章 * 或我开设的 https://github.com/EngTW/English-for-Programmers/issues 或许，将来有一天，《程式英文》累积了足够了「命名」知识与经验，可以试着开 发出某种「命名语意检查工具」，但目前还是得依赖人脑。 ## 技术指导 这个时代有很多很棒的书与参考资料，但我发现既有的参考资料在「命名的语意」 这方面相对的薄弱。而对母语非英语的我们来说还有「英文语意」这个门槛。 经过过去 12 周的尝试，我发现从语源学(etymology)的角度可以有效地厘清英文 字的语意；《程式英文》会继续探讨「程式命名常用字」的语意、字面上的意思 denotation vs. 使用情景中的意思 connotation 、语法、格式。 另一方面，我从学术论文着手，看看学界是怎麽研究「程式命名」这个题目；以下 是我最近读的资料的归纳整理： ### 「命名」的方法 0. 当你想要命名一个东西时 1. 你想要传达的概念有哪些？例如： * 需求，这东西的目的为何？它被用来解决什麽问题？ * 情境，这东西的上下文为何？ * 地雷，这东西有什麽违反直觉、违反业界常规的地方？ * 参考 https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1546163575.A.4C5.html ，还有 哪些概念会让你觉得需要为它写注解？ 2. 把这些概念记录下来 * 不要在意文法、不要在意用字、不要在意篇幅长短 * 先粗略地大量蒐集资料，之後再来精练品质 3. 避开「知识的诅咒」，例如： * 暂时离开这个工作环境，让你的大脑忘掉这一切 * 或着，找人跟你 pair programming, code review, 讨论 4. 把那些概念依重要性排序 * 就团队文化、业界常规来说，有哪些概念是独特到要特别说出来的？ 5. 就最重要的概念来说，有哪些字可以代表该概念？ 6. 用那些字来组合出那东西的名字 7. 找人 code review, 评估你想出来的名字的品质，是否能做到： * 以精练的文字引导程式码读者的大脑聚焦在最重要的相关知识与经验上 * 进而掌握程式码的 How & Why 参考资料： * Feitelson, D., Mizrahi, A., Noy, N., Shabat, A. B., Eliyahu, O., & Sheffer, R. (2020). How Developers Choose Names. IEEE Transactions on Software Engineering. ### 「监定命名品质」的方法 * 命名要适合放在工作记忆区的大小 * 一般人脑大约能同时掌握 3 ~ 4 个概念与那些概念之间的关系 * 一般人脑的「一看就懂」是指在约 2 秒内能看懂一个概念 * 母语为英语者，一般阅读速度是约 1 秒 4 个英文字 * 命名要精练(concise)，例如： * 假设我们想要命名「输出档案的名称」变数 * `output_file_name` 是个好名字，它 正确 且 精练 * `file_name` 会是个 正确 但 不精练 (不严谨) 的名字 * `foo` 是 不正确 也 不精练 * 命名要一致(consistent) * 假设某程式中， `file` 在某个地方代表「档案名称」， * 在另一个地方代表「档案指标(pointer)」， * 这是不一致的 * 这里的问题是「同一个名称 对应到 多个概念」 * 假设某程式中， `file` 在某个地方代表「档案名称」， * 在另一个地方， `file_name` 也代表「档案名称」， * 这也是不一致的 * 这里的问题是「多个名称 对应到 同一个概念」 参考资料： * Deissenboeck, F., & Pizka, M. (2006). Concise and consistent naming. Software Quality Journal, 14(3), 261-282. --- 我还在慢慢消化这些学术论文；如果对我的阅读笔记有兴趣的话，可以看看这些： * https://www.facebook.com/twy30/posts/2641704649413183 * https://www.facebook.com/twy30/posts/2641828296067485 * https://www.facebook.com/twy30/posts/2630596570523991 * https://www.facebook.com/twy30/posts/2592785380971777 * https://www.facebook.com/twy30/posts/2630521400531508 * https://www.facebook.com/twy30/posts/2630473677202947 除了「命名的语意」外，现有的「命名常规」资料似乎也很少提到「型别(type)」 对「程式可读性」的影响；这也是个很有趣的研究方向。 --- # 结语 「命名」这个题目很有趣，像是在打造一把钥匙，可以打开读者的大脑仓库，提取 出一整个世界。 有任何关於软体工程、程式设计的英文相关问题都很欢迎提出来讨论；很多很有趣 的研究方向、灵感其实都是来自於读者提问、意见回馈。 在此感谢所有参与讨论的网友 :) --

※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 136.56.13.184 (美国) ※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1601675826.A.A6D.html 谢谢各位的欣赏 :) ※ 编辑: AmosYang (136.56.13.184 美国), 10/05/2020 02:04:53 如果你是指 var_name 与 var-name 这两种写作风格的差异， * 我目前尚未看到任何认知科学研究主张哪种比较好、怎麽个好法。 * 我目前看到的多是「在这个文化生态圈中，就是习惯这样写」。 --- 很像是「小数点」的情形；例如 * 10,000.00 ← 台、美、日等国家习惯用 "." 来当小数点 * 10.000,00 ← 欧洲、一些非州国家则是用 "," 来当小数点 没有资料说哪种比较「好」，就是文化习惯。 参考资料： https://en.wikipedia.org/wiki/Decimal_separator ※ 编辑: AmosYang (136.56.13.184 美国), 10/05/2020 04:29:36 谢谢各位的欣赏 :) ※ 编辑: AmosYang (136.56.13.184 美国), 11/08/2020 12:56:41