提高代码可读性

Question

对于代码文档，通常认为代码应该自己解释，并且内联代码文档（不包括公共API文档）应该只解释元代码问题，例如变通方法，解释选择具体实施的原因等等。

如何让您的代码更具可读性，更多解释自己？

<小时/> 编辑除了一般性评论之外，我还在寻找具体提示。因此，如果您说“短而有意义的变量名称”，那么也可以获得有用的提示（例如“使用三字原则”）。

Answer 1

查看Jeff Atwood的Code Smells博文。它几乎总结了它。在谈到良好的可读代码时，我将添加我的个人精神：

• 一致性这适用于格式化，使用大括号，命名（变量，类，方法）和目录布局（如果你在/ css下的某个地方埋藏一个源目录我会跟着你弯刀）;
• 大小：如果某个功能在普通IDE中以正常字体大小完全不适合屏幕，那么你需要一个非常好的理由来解释原因。当然，有一些有效案例可以用于更长时间的功能，但是它们被极其严重的例子大大超过了它们。根据需要进行分解以保持功能简单;
• 评论明智地：某些程序员倾向于使用注释代替可读代码或仅仅为了评论而评论（例如/* finished */评论之前{{} 1}}。说真的，重点是什么？大多数（好的）代码解释了自己;
• 永远不会在项目中剪切和粘贴：从一个项目到另一个项目（每个项目都是岛屿）的代码片段是完全可以接受的，但是你应该从不采取从一个项目内到项目中某个其他点的非平凡代码段。不可避免地有一个变化，你让一些可怜的开发人员负责查看这两个或更多代码段，试图弄清楚他们是如何（并且可以说更重要的是，为什么）不同;和
• 避免重复代码：如果您发现自己一遍又一遍地编写相同的语句序列（或非常相似），则对其进行抽象或参数化。如果你看到非常相似的陈述，那么倾向于略过它们，假设它们完全相同（通常情况下它们的重要性并不重要）。

Answer 2

• 一致的格式化风格
• 善用空白
• 使用简短但有意义的名字
• 没有太多评论（如你所述），但当我这样做时，请评论代码的为什么，如果适用，为什么不（为什么没有'使用其他一些实现，特别是如果看起来这样做应该是显而易见的。）
• 在分析器告诉我速度慢或效率低之前，不要优化代码

Answer 3

使用好的变量和方法名称。将代码分解为有意义的部分，以实现特定目的。让你的类具有凝聚力（它们一起工作）和解耦（类之间几乎没有依赖关系）。不要重复自己（干）。跟随鲍勃叔叔的SOLID principles（不是法律，正如他points out），他们努力使代码更好。

Answer 4

来自'uncle bob'的书清洁代码通过实际操作示例为您提供了关于功能应该如何的完整概述。

一些要点：

• 小功能，班级
• 好，有意义，名字，大小无关紧要，但应该尽可能长“
• 函数/变量之间的垂直间距应该较低（声明尽可能接近首次使用的位置）
• 函数和类应该只做一件事，

这本书有很多小规则，我真的推荐它。也可以获得Code Complete 2。

Answer 5

自我记录代码是：

• 良好的命名惯例
• 明确设计和组件之间的责任分离（类，功能等）

但请记住，即使是最自我记录的代码也只能记录那里的内容;从来没有故意遗漏，优化，尝试和丢弃等等。基本上，你的源文件中总是需要英语，或者你必须遗漏重要的警告和设计决定。

Answer 6

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

我认为应该记录您的界面。我的意思是应该有关于类和方法的注释。当然不是像set和get这样简单的方法。

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

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

Answer 7

您和同事之间有一个Coding Convention。从缩进开始，覆盖括号，直到“花括号来到哪里：新行，同一行？”

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

Answer 8

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

一个明显的例子是在.NET中使用Pascal case作为方法，在Java中使用camel case。

不太明显的例子涉及使用与标准类库中使用的约定相同的约定。

这个目标还有很多要说的。命名约定为人类传达了大量信息，而编译器则很少。任何在一个使用其他环境约定的环境中使用API​​的人都已经注意到了外来代码的突出程度。

一致性是一种有价值的特征，可以降低人类代码消费者的认知负担。

Answer 9

Eschew codejunk。

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

我认为应用于代码的相同思维方式为我们带来了更清晰的代码。示例包括/* getFoo() gets the foo */式注释，不必要的括号和大括号，过度特定的变量名称以及匈牙利符号疣。

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

Answer 10

所有回复（和问题）均基于可读性完全由代码编写者负责的假设。如果你真的不想阅读代码并且你现在有一个放弃阅读列表（代码闻起来），它匹配99％的可用代码，你实际上并不想要考虑一些代码正在做什么，那么你就不会找到任何可读的代码。

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