【发布时间】：2008-09-02 12:29:46
【问题描述】：
您如何编写易于被其他人阅读并且没有亲自编写过代码的任何部分的代码？
【问题讨论】：
标签： readability
【发布时间】：2008-09-02 12:29:46
【问题描述】：
确保其他人可以阅读您的代码的最佳方法是确保代码清晰简洁。即，
- 为变量、函数和类使用自记录名称。
- 评论复杂的算法，这样读者就不必花很长时间弄清楚它的作用。
- 确保整个代码中的制表符和换行符保持不变。
除了你开始进入可能有点主观的领域之外，大多数人应该同意这些项目。
【讨论】：
您可能想看看 Robert C. Martin 的 Clean Code。它提供了许多有用的实践来确保您的代码可读。
此外，如果您的代码受到大量对您的代码进行全面测试的单元测试的支持，那么它为您的用户提供了一种通过查看测试执行的内容来理解代码的方法。您还会发现，如果您遵循测试驱动开发流程，并为每一个功能编写测试，您的功能往往会很小，只做一件事并且做得很好，并且往往更像一个故事而不是简单地流动一个庞大而复杂的“东西”网络。
测试往往比 cmets 更能保持最新。我经常忽略 cmets，因为它们很快就会过时。
【讨论】：
这个问题是主观的，应该避免在 StackOverflow 上，根据 FAQ
我不应该问什么样的问题 在这里问？
避免提出以下问题 主观的、争论的或要求的 扩展讨论。这是一个地方 对于可以回答的问题！
简短的回答是：
-
避免过多评论：
// add one to the count: i++; -
使用好的变量和方法名：
int x = i + j; int runSum = prevSum += newValue; -
在可用的情况下使用编码简写：
if (x == y) { z = a; } else { z = b; } z = (x == y) ? a : b;
【讨论】：
-
您需要将 z == a & z == b 更改为 z = a 和 z = b。
-
-1：您以傲慢地主张 SO 政策开始回答。然后，正如@Crossbrowser 指出的那样，您发布了一个不合逻辑的代码 sn-p。
-
你好，吉姆，你只是在攻击我的个人资料吗？谢谢 - 我感谢您的关注！ :) 试图帮助建立一个社区，这样我们就可以一起工作，这并不傲慢。其次，代码并非不合逻辑，它是不正确的！可悲的是，由于我的编程技能如此之低，我两次点击“=”进行评估而不是分配。我将如何应对！特别是因为没有人能读懂它并明白我想说的话。我会做光荣的事，现在在工作中交出我的通知。感谢@Crossbrowser 在第一个实例中指出它:)
-
不错的答案，但我对最后一部分不太确定。我相信这两种语法都一样容易阅读。
保持代码美观、清晰和简单。不要在很明显的时候评论你正在做的事情（例如我知道 foreach 或 if 做了什么，我通常不需要解释）。
使简单的事情占用更少行数的代码技巧（例如自动属性）也很好。
【讨论】：
购买并阅读Code Complete 2。那里有很多关于编写易于阅读/维护的代码的内容。
【讨论】：
我不认为这是一个主观问题，但它太宽泛了！这不仅仅是评论和给出好的变量名称。它涉及人类如何理解代码。因此，您的系统必须以一种方式实现，以便读者可以通过两种方式轻松构建其设计的心理模型：
自上而下：假设用户知道系统域，他倾向于对其实现方式做出假设，因此他将扫描系统包和类以寻找他可以识别的实体。给你的类起个好名字并适当地模块化它会很有帮助。
自下而上：一旦用户到达代码的一部分，他将从那里开始导航，构建知识块。如果您的系统内聚度低且存在大量隐式依赖项，则用户将会丢失。
Kent Beck 采用三个原则：沟通、简单和灵活。当然，有时您必须以简单性换取灵活性，反之亦然。
这可能会一直持续下去。这个问题的答案适合一本大书。正如@rmbarnes 建议的那样，购买并阅读 Code Complete 2。我还建议 Kent Beck 的 Implementation Patterns - 它与您的问题高度相关。
【讨论】：
- 记录代码，说明它为什么这样做。
- 确保所有变量函数等的命名一致且具有描述性
- 使用空格将代码的逻辑部分组合在一起，以便在阅读时流动。
- 按逻辑顺序放置函数/方法等。
- （这个是我个人的偏好）确保代码可以在屏幕上轻松阅读，而无需水平滚动（有些人也说垂直滚动，但这似乎并不困扰我）。
【讨论】：
-
-1：1.记录代码，说明它为什么会这样做。 - 祝你好运，让文档保持最新。 有些人也说垂直，但这似乎并不困扰我 - 这么长的函数和方法不会打扰你？
-
1.我的方法名称不是段落，那为什么还要打扰我呢？我有 IDE 可以为我自动填充方法名称。我会在一周中的任何一天使用更长的名称来编写令人困惑的代码。在我工作的地方，我们会花时间确保我们编写的所有代码都被记录和审查，所以是的，它几乎总是最新的。如果不是，在review中注明，程序员回去修复它，这是程序员决定的，不是经理强迫的，所以每个人都遵循它，因为我们知道它的重要性。我认为你不这样做？
由于其他人几乎都说了我在阅读这个问题时的想法，所以我将分享两本与该主题相关的书籍，您可能有兴趣阅读。这些书籍使用开源代码示例来解释如何阅读和编写高质量的代码。除了 Code Complete，我认为当你想用任何语言编写好的代码时，它们都是宝贵的资源。
【讨论】：
我的规则：
- 给所有事物起一个有意义的名字，并称其为。避免对变量使用“x”和“y”。
- 不要缩写任何东西。我不在乎变量名有多长，不要缩写，即使是 cmets。缩写的解释是主观的。 Cmp是电脑的意思吗？电脑？公司？赞扬？让它成为一个强有力的规则，没有例外，并且易于遵循。
- 不要将多个语句放在同一行。每行执行一个操作。
- 避免像瘟疫一样使用匈牙利符号。还是ntHungarian？
- 即使对于单行（if、for）子结构，也要使用括号。缩进差异太容易丢失了。
【讨论】：
这里有很多好的答案，我想从喜欢大局的工程师的角度补充一些东西。我经常发现，就类图或包级别概述（图/cmets 等）而言，获得高级概述，见鬼，如果文件中不存在 10 行标题 cmets 对我有很大帮助。我们可以使用 Doxygen/Javadocs 来生成它们，或者花 10-15 分钟在 cmets 部分记下一些东西。
它们不必是 100% 准确的，我怀疑类/包的整体结构会在不完全重写的情况下发生变化。
我个人认为这种全局概览非常有帮助，并且相信其他人也有同样的感受。
【讨论】：
可能最重要的一点是保持语法一致。我还想看看你所用语言的设计指南。
【讨论】：
我很可能属于少数，但我不介意空格。我爱空白。由于编译器将其取出并且高清空间非常便宜，我喜欢在我的代码中使用空白空间。
比如我喜欢：
int total = 10;
int sum = 0;
for (int i = 0; i < total; i++)
{
sum += i;
}
// Next coding statement is a space below the bracket
return sum;
我不喜欢：
int total = 10;int sum = 0;
for (int i = 0; i < total; i++)
{
sum += i;
}
return sum;
即使从技术上讲，我也将它们放在括号中。最好的例子是 if 语句。我发现它极大地提高了可读性。
if(true)
// some action
if(true)
{
// Some action
}
对我来说最好的代码是尽可能简单的代码。使用尽可能少的 cmets，最重要的是 有效。
【讨论】：
作为一名拥有多年经验的开发人员，这对我来说曾经是一个真正的问题。我什至无法说出我花了多少小时思考这个问题并在我的代码中尝试不同的东西。上面的答案也很好。我只想添加一两件事。
我们每个人都有不同的东西使我们的阅读与其他人不同。你觉得很容易阅读的东西，别人可能真的很难阅读。
代码的清洁度是一个非常重要的方面。一旦它变得太拥挤就忘记它。
最重要的是：你是你自己的老师。无论您遵循哪种风格，您都希望根据自己的经验改变一两件事。几个月过去了，您必须回到旧的修复程序或文档中，您将获得“我不敢相信我编写的代码看起来像那样”的效果。记下对代码可读性造成困扰的问题，并确保不要再这样写。
【讨论】：