如何在没有“需要”注释的情况下编写代码以提高可读性？

Question

  

可能重复：
  Is it possible to write good and understandable code without any comments?

经常编码时，我听说如果需要评论，那就意味着代码太难理解了。我同意代码应该是可读的，但由于“管道”和奇怪的语法，语言本身通常会使代码难以遵循。我经常使用的语言是：

爪哇 MooTools的 红宝石 二郎

任何提示都会受到赞赏吗？ 感谢

Answer 1

推荐阅读：Robert C. Martin的Clean Code。

简而言之，你应该

• 使用有意义的变量/方法/类名，
• 保持您的功能/方法简短，
• 让每个班级和方法只做一件事，
• 让每个方法中的代码处于相同的抽象级别。

不要害怕从if语句中提取中等复杂的表达式;哪个更清楚，这个

if (i >= 0 && (v.size() < u || d == e)) ...

或

if (foundNewLocalMaximum()) ...

（不要试图在第一个代码片段中找到任何含义，我只是编写了： - ）

几乎不需要干净代码中的注释。我能想到的唯一例外是你使用了一些模糊的语言特性（例如C ++模板元编程）或算法，并且你在评论中提供了方法/算法的来源及其实现细节的参考。

从长远来看，任何其他类型的注释都没有用处的主要原因是代码更改，并且注释往往不会随着相应代码中的更改而更新。所以过了一段时间评论不是简单的无用，但它有误导性：它告诉你一些事情（实现说明，关于设计选择的推理，错误修复等），这些指代代码的版本已经很久了，你有不知道它是否与当前版本的代码相关。

我认为“为什么我选择这个解决方案”的另一个原因通常是不值得在代码中记录，这个评论的简短版本几乎总是像“因为我觉得这是最好的方式” “，或参考例如“C ++编程语言，第5.2.1节”，以及长版将是一篇三页的文章。我认为一个经验丰富的程序员经常看到并理解为什么代码是这样编写的，没有太多解释，初学者甚至可能无法理解解释本身 - 不值得尝试覆盖每个人。

最后但同样重要的是，IMO单元测试几乎总是比代码注释更好的文档管理方式：您的单元测试确实可以非常有效地记录您对代码的理解，假设和推理，而且会自动提醒您保持同步每当你打破它们时使用代码（好吧，只要你实际使用你的构建运行它们......）。

Answer 2

我认为你通常不会在没有评论的情况下编写代码。

简单地说，代码文档如何。评论文件为什么。

我希望这些评论能够指出代码编写的条件，需求或外部因素所带来的限制，更改代码所带来的影响以及其他问题。注释包含代码本身未包含的信息。

Answer 3

代码中的注释应该告诉你为什么你最初以某种方式做某事。这并不意味着代码太难理解。

Answer 4

最重要的事情是：

• 给你的变量，方法，类......有意义的名字
• 编写清洁责任的课程/模块
• 不要混淆不同级别的代码（不要在一种方法中进行位移和高级逻辑）

Answer 5

我认为为代码的USERS编写注释是有用的 - 类/方法/函数的作用，何时调用它等等。换句话说，记录API。

如果你需要评论一个方法如何为维护者的利益工作，那么我认为代码可能太复杂了。在这种情况下，将其重构为更简单的功能，正如其他人所说的那样。

Answer 6

我个人觉得完全没有评论就像过度评论一样糟糕。你只需要找到合适的平衡点。关于为事物使用长描述性名称，这总结了我：read this同时阅读Kernighan＆amp;派克长名。

Answer 7

您需要遵守某些规则。

• 为实体（变量，类等）提供可读且有意义的名称。
• 广泛使用设计模式并相应地命名，例如：如果它是Factory名称FooFactory。
• 正确格式化代码等