知识卡片

逐字翻译测试法:把代码翻译成中文读给别人听,检验可读性是否真的合格

普通读书笔记卡

内容

评价一段代码能不能让人看懂,一个可操作、可执行的具体方法是:让代码作者把这段代码逐字翻译成中文,试着组成通顺的句子,再把这些中文句子读给一个没有看过这段代码的人听——如果对方能听懂,这段代码的可读性基本就算合格了。这个方法的合理性在于它精确复现了真实的代码阅读过程:其他人理解一段代码时,本来就是一个词一个词地阅读、推断句子的意思,如果单靠这句代码本身理解不了,就要联系上下文,如果联系上下文还理解不了,可能还要掌握更多其他部分的细节才能推断出含义——理解一句代码所需要联系的上下文越多,通常就意味着这段代码的质量越差。逐字翻译的最大好处是能让作者自己轻易发现那些”只有自己知道、却没有真正体现在代码里”的隐藏假设和可读性陷阱——那些无法从字面意义上直接翻译出原本含义的代码,大多数就是烂代码,典型例子包括”ms代表messageService”这类只有作者自己心里明白的缩写映射、或者”tmp代表当前的文件”这种变量名和实际含义完全脱节的命名。这个方法的价值在于把一个原本模糊、依赖主观判断的问题(”这段代码可读性好不好”),转化成了一个具体、可执行、任何人都能操作的测试步骤——不需要评价者本身具备很高的经验判断力,只需要按这个流程走一遍,代码里有没有”只有作者自己懂”的隐藏假设就会自然暴露出来,这正是把抽象的质量原则转化为具体操作方法的一个典型范例。

参考来源

- 位置:《高可用架构(第1卷)》第5章《运维保障》"5.6 系统运维之评价代码优劣的方法"节,"5.6.1 什么是好代码"(源文件:_epub-src/OEBPS/Text/Chapter5_6_2.xhtml) - 结论依据:原文说明"在评价一段代码能不能让人看懂的时候,我习惯让作者把这段代码逐字翻译成中文,试着组成句子,之后把中文句子读给另一个没有看过这段代码的人听,如果另一个人能听懂,那么这段代码的可读性基本就合格了……逐字翻译的好处是能让作者轻易地发现那些只有自己知道的,没有体现在代码里的假设和可读性陷阱",直接支撑本卡片结论。 - 原始内容:在评价一段代码能不能让人看懂的时候,我习惯让作者把这段代码逐字翻译成中文,试着组成句子,之后把中文句子读给另一个没有看过这段代码的人听……逐字翻译的好处是能让作者轻易地发现那些只有自己知道的,没有体现在代码里的假设和可读性陷阱,比如"ms代表messageService"。