你如何编写代码,让那些不曾参与其中任何部分的人很容易阅读?

确保其他人能够读取代码的最佳方法是确保代码清晰明了。即,

• 为变量、函数和类使用自文档名称。
• 对复杂的算法进行评论,这样读者就不必花太多时间去弄清楚它的作用。
• 确保制表符和换行符在整个代码中保持不变。

除此之外,你开始进入可能有点主观的领域,大多数人应该同意这些项目。

你可能想看看 Clean Code 罗伯特·马丁。它为确保代码可读性提供了许多有用的实践。

此外,如果您的代码得到了许多单元测试的支持,这些单元测试可以彻底测试您的代码,那么它为您的用户提供了一种通过查看测试正在执行的操作来理解代码的方法。您还将发现,如果您遵循测试驱动的开发过程,并且为每一个功能位编写测试,那么您的功能往往很小,只做一件事并且做得很好,而且往往更像一个故事,而不是一个由“东西”组成的大型复杂网络。

测试往往比评论更为及时。我经常忽略评论,因为它们很快就过时了。

这个问题是主观的,根据 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;
  

保持代码美观、清晰和简单。不要评论你在做什么,当它是显而易见的(例如,我知道什么foreach或如果做,我通常不需要解释)。

代码技巧(如自动属性)使简单的事情占用更少的行也很好。

购买和阅读 Code Complete 2 . 这里有很多关于编写易于阅读/维护的代码的东西。

我不认为这是个主观问题,但太宽泛了!不仅仅是评论和给出好的变量名。它涉及人类如何理解代码。因此,你的系统必须以一种方式来实现,读者可以通过两种方式轻松地构建其设计的心智模型:

• 自上而下:假设用户知道系统域,他倾向于对它如何实现进行假设,所以他会扫描系统包和类,寻找他能识别的实体。给你的类起个好名字,并适当地模块化它将非常有帮助。

• 自下而上:一旦用户到达代码的一部分,他将从那里开始导航,构建知识块。如果您的系统内聚性低,并且有很多隐式依赖项,那么用户将丢失。

Kent Beck采用了三个原则:沟通、简单和灵活。当然,有时候你不得不用简单来换取灵活性,反之亦然。

这可能会持续下去。这个问题的答案适合一本大书。按照@RMBARNES的建议,购买并阅读代码完成2。我也建议 Implementation Patterns 作者:肯特·贝克-这与你的问题密切相关。

1. 记录代码,说明为什么要这样做。
2. 确保所有变量函数等的命名一致且具有描述性。
3. 使用空白将代码的逻辑部分分组在一起,以便在读取时流动。
4. 按逻辑顺序排列函数/方法等。
5. (这是我个人的偏好)确保代码可以很容易地在屏幕上读取而不必水平滚动(有些人也说垂直,但这似乎不打扰我)。

既然其他人都说了我读这个问题时的想法,我就分享两本你可能感兴趣的关于这个主题的书。这些书使用开放源码的例子来解释如何阅读和编写高质量的代码。除了完整的代码外,我认为当你想用任何语言编写好的代码时,它们都是很有价值的资源。

• Code Reading: The Open Source Perspective
• Code Quality: The Open Source Perspective

我的规则:

1. 给每件事起一个有意义的名字,叫它什么名字。避免对变量使用“x”和“y”。
2. 不要缩写任何东西。我不在乎变量名有多长,不要缩写,即使有注释。缩略语的解释是主观的。CMP是指计算机吗?电脑?公司?恭维话?使它成为一个强有力的规则,没有例外,并且易于遵循。
3. 不要把多个语句放在同一行。每一行执行一个动作。
4. 避免匈牙利符号如瘟疫。或者是南桑加利亚人?
5. 即使对于单线(如果,对于)子结构,也要使用括号。压痕差异太容易丢失。

可能最重要的一点是保持语法的一致性。我还要看一下你所用语言的设计指南。

我很可能是少数,但我不介意空白。我喜欢空白。由于编译器将其取出,而且hd空间非常便宜,所以我喜欢在代码中使用空白。

例如,我喜欢:

        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
}

对我来说,最好的代码是尽可能简单的代码。尽可能少的评论,最重要的是 作品 .

这里有很多好的答案,我想从一个喜欢大局的工程师的角度补充一点。我经常发现,从类图或包级概述(图/注释等)的角度获得一个高级概述,会检查文件中是否没有10行的头注释来帮助我。我们可以使用doxGe/javaDoc来生成它们,或者花10-15分钟来记下评论部分中的内容。

它们不必100%精确,而且我怀疑没有完全重写,类/包的总体结构是否会改变。

我个人认为,这种大局观非常有帮助,相信还有其他人也有同样的感受。

从做了几年的开发商开始,这对我来说是个真正的问题。我甚至说不出我花了多少时间来思考这个问题并在代码中尝试不同的东西。上面的答案也很好。我只想加一两件事。

• 我们每个人都有不同的东西,使我们的阅读不同于其他人。你觉得容易阅读的东西,可能真的很难被别人阅读。

• 代码的清洁是一个非常重要的方面。一旦它变得太狭窄了,就忘掉它吧。

• 最重要的是:你是自己的老师。不管你遵循什么风格,你都会想根据你的经验改变一两件事。几个月过去了,你必须回到旧的修复或文档中,你会得到“我不敢相信我写的代码读得像这样”的效果。记下用代码可读性困扰你的内容,确保不要再这样写。