24

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

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

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

4

10 回答 10

33

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

  • 一致性：这适用于格式化、使用大括号、命名（变量、类、方法）和目录布局（如果你将源目录埋在 /css 下的某个地方，我会用砍刀追你）；
  • 大小：如果一个函数不能以正常的字体大小在正常 IDE 的屏幕上完全显示，那么你需要一个很好的理由来说明为什么不这样做。当然，对于更长的函数，也有一些有效的案例，但这些案例远远超过了这些令人震惊的例子。根据需要进行分解以保持功能简单；
  • 明智地评论：一些程序员倾向于使用评论来代替可读代码，或者只是为了评论而评论（就像/* finished */之前的评论一样return true;。说真的，有什么意义呢？大多数（好的）代码可以自我解释；
  • 永远不要在项目中剪切和粘贴：将代码片段从一个项目转移到另一个项目是完全可以接受的（每个项目都是一个孤岛），但你永远不应该将一个项目中的重要代码段转移到项目中的其他点. 不可避免地会发生一个变化，而你让一些可怜的开发人员负责查看这两个或更多代码段，试图找出它们的不同之处（可以说更重要的是，为什么）；和
  • 避免重复代码：如果您发现自己一遍又一遍地编写相同的语句序列（或非常相似的语句），请将其抽象或参数化。如果您看到非常相似的陈述，则倾向于略过它们，假设它们都是相同的（通常它们不会以某种重要的方式出现）。
于 2009-02-15T14:06:34.383 回答
8
  • 一致的格式样式
  • 善用留白
  • 使用简短但有意义的名称
  • 没有太多评论（正如你提到的），但是当我这样做时，评论代码的原因，如果适用，为什么不评论（为什么不使用其他一些实现，特别是如果它看起来应该是显而易见的所以）。
  • 在分析器告诉我代码缓慢或效率低之前，不要优化代码
于 2009-02-15T13:30:21.367 回答
8

使用好的变量和方法名称。将代码分解成有意义的片段以实现特定目的。保持你的类的凝聚力（它们一起工作）和解耦（类之间几乎没有依赖关系）。不要重复自己（干）。遵循 Bob 叔叔的SOLID 原则（而不是法律，正如他所指出的那样），以使代码变得更好。

于 2009-02-15T13:30:59.680 回答
5

来自'uncle bob' 的书清洁代码通过动手示例为您提供了函数应该是什么样子的一个很好的概述。

一些重要的点：

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

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

于 2009-02-15T13:36:30.807 回答
4

自记录代码是：

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

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

于 2009-02-15T13:32:14.030 回答
4

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

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

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

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

于 2009-02-15T14:20:04.430 回答
2

在你和你的同事之间有一个编码约定。从缩进开始，覆盖括号直到“大括号从哪里来：新行，同一行？”

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

于 2009-02-15T13:30:22.660 回答
1

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

一个明显的例子是 .NET 中的方法使用 Pascal 案例，Java 中的骆驼案例。

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

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

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

于 2009-02-15T13:38:42.797 回答
1

避开代码垃圾。

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

我认为同样的想法，应用于代码，给我们带来了更清晰的代码。示例包括/* getFoo() gets the foo */- 样式的注释、不必要的圆括号和大括号、过于具体的变量名称和匈牙利符号缺陷。

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

于 2009-04-19T15:23:18.400 回答
0

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

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

于 2009-02-15T22:16:36.140 回答