提高代码可读性 [关闭]答案

【问题标题】：Improving Code Readability [closed]提高代码可读性 [关闭]
【发布时间】：2010-10-07 17:49:59
【问题描述】：

当涉及到代码文档时，通常认为代码应该自我解释，而内联代码文档（不包括公共 API 文档）应该只解释元代码问题，例如解决方法、解释为什么选择特定的实现等等。

您如何使您的代码更具可读性和解释性？

编辑：除了一般的 cmets，我也在寻找具体的提示。因此，如果您说“简短但有意义的变量名”，也可以得到一个有用的提示（例如“使用三字原则”）。

【问题讨论】：

为什么这个问题不被迁移到softwareengineering.stackexchange.com？

标签： language-agnostic documentation readability

【解决方案1】：

查看 Jeff Atwood 的 Code Smells 博客文章。它几乎总结了它。当谈到可读性好的代码时，我会补充我的个人精神：

一致性：这适用于格式化、使用大括号、命名（变量、类、方法）和目录布局（如果您将源目录埋在 /css 下的某处，我会用砍刀追赶您）；
大小：如果一个函数不能以正常的字体大小在正常 IDE 的屏幕上完全显示，那么你需要一个很好的理由来说明为什么不这样做。当然，对于更长的函数，也有一些有效的案例，但这些案例远远超过了这些令人震惊的例子。根据需要进行分解以保持函数简单；
谨慎评论：有些程序员倾向于使用 cmets 作为可读代码的替代品，或者只是为了评论而发表评论（例如 /* finished */ cmets 就在 return true; 之前。说真的，什么是重点是什么？大多数（好的）代码都能自我解释；
切勿在项目中剪切和粘贴： 将代码 sn-p 从一个项目带到另一个项目是完全可以接受的（每个项目都是一个孤岛），但您应该从不从一个项目内到项目内其他点的重要代码段。不可避免地会发生一个变化，而你让一些可怜的开发人员负责查看这两个或更多代码段，试图找出它们的不同之处（可以说更重要的是，为什么）；和
避免重复代码：如果您发现自己一遍又一遍地编写相同的语句序列（或非常相似的语句），请将其抽象或参数化。如果您看到非常相似的陈述，则倾向于略过它们，假设它们都是相同的（通常它们不会以某种重要的方式出现）。

【讨论】：

【解决方案2】：

避开代码垃圾。

Edward Tufte 拥有美丽而强大的chartjunk 概念，图表中的视觉元素会产生噪音而不是信息。通过以这种方式思考图表，我们可以制作出更清晰的图表。

我认为将同样的思维应用于代码，可以为我们带来更简洁的代码。示例包括 /* getFoo() gets the foo */ 样式的 cmets、不必要的圆括号和大括号、过于具体的变量名称和匈牙利符号缺陷。

什么构成图表垃圾取决于团队、环境和项目——有些人喜欢疣；某些环境以使某些垃圾有用的方式呈现代码（例如考虑大括号匹配和// end for cmets）；一些项目需要更广泛的评论以符合标准或全面记录 API。但是，当一个团队建立了图表垃圾对其项目意味着什么的标准时，许多决策变得更加容易，其代码也变得更加一致和可读。

【讨论】：

【解决方案3】：

所有回复（和问题）都基于这样的假设，即可读性完全是代码编写者的责任。如果你真的不想阅读代码并且你有一个现在放弃阅读列表（代码有异味），它匹配 99% 的可用代码并且你实际上甚至不想非常努力地思考某些代码在做什么，那么你将找不到任何可读的代码。

无论我们今天使用什么规则来使我们的代码更具可读性，在 10 年后都会显得过时和愚蠢。如果您真的想要更好的代码可读性，请阅读一些旧代码（考虑到当时的时尚，它必须在您拥有的速度和内存的 1000 倍的机器上运行），努力理解它并鼓励其他人做同样的事情。

【讨论】：

【解决方案4】：

坚持在您编码的环境中使用的范例。

一个明显的例子是在 .NET 中对方法使用 Pascal 大小写，在 Java 中使用骆驼大小写。

不太明显的示例与使用与标准类库中使用的约定相同的约定有关。

对于这个目标有很多话要说。命名约定为人类传达了很多信息，而对编译器来说却很少。任何在一个环境中使用过使用另一种环境约定的 API 的人都会注意到外来代码有多么突出。

一致性是一个有价值的特征，可以减少人类代码使用者的认知负担。

【讨论】：

【解决方案5】：

我通常不会在代码内部发表评论，但我完全不同意人们经常持有的观点，即应该只编写可读的代码，然后就不需要文档。

我认为应该记录的是你的界面。我的意思是在类和方法之上应该有 cmets。当然不是像 set 和 get 这样的简单方法。

使用您编写的类和方法的人不必阅读您的代码即可了解如何使用它们。所以我认为应该记录什么是合法的输入和输出范围以及重要的不变量。例如。函数将指针作为参数。无论您如何为函数命名，提供 NULL 是否有效或 NULL 是否是有效的返回结果都不是很明显。通常，-1 和 0 用于表示某些东西，例如搜索未找到的对象或类似的东西。这应该记录在案。

除此之外，我认为记录代码的关键不是记录类或方法做什么或是什么，而是记录意图是什么 后面就是。

【讨论】：

【解决方案6】：

来自“uncle bob”的这本书干净的代码通过动手示例让您很好地概述了函数的外观。

一些要点：

小函数、类
好，有意义，名字，大小无关紧要，但应该完全符合需要
函数/变量之间的垂直间距应该很小（声明的东西尽可能接近首次使用的位置）
函数和类应该只做一件事和一件事

这本书还有很多小规则，我真心推荐。同时获得 Code Complete 2。

【讨论】：

【解决方案7】：

自记录代码是：

良好的命名约定
清晰的设计和组件（类、功能等）之间的职责分离

但请记住，即使是最自我记录的代码也只能记录那里的内容；永远不要故意遗漏、优化、尝试和丢弃的内容等。基本上，在源文件中，您总是需要英语，否则您必然会遗漏重要的警告和设计决策。

【讨论】：

【解决方案8】：

使用好的变量和方法名。将代码分解成有意义的片段以实现特定目的。保持你的类的凝聚力（它们一起工作）和解耦（类之间几乎没有依赖关系）。不要重复自己（干）。遵循鲍勃叔叔的SOLID principles（不是法律，因为他是@987654322@），他们努力使代码变得更好。

【讨论】：

【解决方案9】：

在您和您的同事之间使用Coding Convention。从缩进开始，覆盖括号直到“大括号从哪里来：新行，同一行？”

在 Visual Studio 中，可以选择并修复此样式。它可以帮助您团队中的所有其他人阅读相同的代码。当您不必区分“空”编辑（样式更改）和实际编辑时，它还使版本控制系统中的历史跟踪变得更加容易。

【讨论】：

说真的，您是否认为大括号的放置是代码是否可读的最重要方面？
没有。我不。但其他人这样做。所以它是编码约定的一部分。它是垂直布局的一部分。

【解决方案10】：

一致的格式样式
善用空白
使用简短但有意义的名称
没有太多 cmets（正如您提到的），但是当我这样做时，请注释代码的 为什么，如果适用，请注释 为什么不（为什么不是t 使用了其他一些实现，特别是如果这样做看起来应该很明显）。
在分析器告诉我代码缓慢或效率低之前，不要优化代码

【讨论】：