如何编写代码而不需要“需要”注释以提高可读性？ [复制]答案

【问题标题】：How can I write code without "needing" comments for readability? [duplicate]如何编写代码而不需要“需要”注释以提高可读性？ [复制]
【发布时间】：2011-01-16 11:31:55
【问题描述】：

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

在编码时，我经常听说如果需要 cmets 则意味着代码太难理解。我同意代码应该是可读的，但由于“管道”和奇怪的语法，语言本身常常使代码难以理解。我最常使用的语言是：

Java 穆工具红宝石二郎

任何提示将不胜感激？谢谢

【问题讨论】：

复制：stackoverflow.com/questions/784250/…
请注意，代码无法告诉您为什么某事以特定方式完成，只能告诉您如何。
这是一个只有 cmets 才能说出“为什么”的神话。有时您确实需要对此进行注释，但通常代码可以说明整个故事。看，评论还不错。但是考虑到 cmets 的需求是一个信号，表明代码也许可以变得更清晰。

标签： java ruby erlang comments mootools

【解决方案1】：

我认为没有 cmets 你通常无法编写代码。

简而言之，代码文档如何。 cmets 文档为什么。

我希望 cmets 指出为什么要这样编写代码的条件、需求或外部性施加的限制、更改代码可能产生的影响以及其他问题。 cmets 包含代码本身不包含的信息。

【讨论】：

@Brian：当代码更改时，什么保证这些 cmets 会相应更新？一个注释告诉我为什么 n 年前代码的原始版本 - 通常与当前版本没有丝毫相似之处 - 是按原来的方式编写的，有什么用？跨度>
@Peter 您保证通过代码审查或结对编程来更新 cmets。
我会建议更多地关注编写自文档代码而不是编写 cmets。我经常在代码中看到太多不需要的 cmets。
@Peter - 恐怕没有什么能提供您所追求的保证。您必须将代码和 cmets 一起维护。鉴于上述标准，我希望代码比 cmets 更频繁地更改。厘米。
@Peter：自我记录“为什么”非常困难，要完全做到这一点，您最终会得到像“HashMap aConcurrentHashMapIntentionallyNotUsedHereBecauseOfTheUsagePattern”这样的变量名称

【解决方案2】：

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

简而言之，你应该

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

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

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

或

if (foundNewLocalMaximum()) ...

(不要试图在第一个代码sn-p中找到任何意义，我只是编造的:-)

几乎从不需要干净代码中的注释。我能想到的唯一例外是，如果您使用了一些晦涩难懂的语言功能（例如 C++ 模板元编程）或算法，并且您在评论中提供了对方法/算法的来源及其实现细节的引用。

从长远来看，任何其他类型的 cmets 不是很有用的主要原因是代码更改，并且 cmets 往往不会随着相应代码的更改而更新。所以过了一会儿，评论不仅没有用，而且具有误导性：它告诉你一些东西（实现说明、关于设计选择的推理、错误修复等），它指的是一个早已不复存在的代码版本，而你有不知道它是否与当前版本的代码相关。

我认为“我为什么选择这个解决方案”通常不值得在代码中记录的另一个原因是，这种评论的简短版本几乎总是像“因为我认为这是最好的方式"，或引用例如“The C++ Programming Language, ch. 5.2.1”，加长版将是一篇三页的文章。我认为一个有经验的程序员最经常看到并理解为什么代码会这样写而没有太多解释，而初学者可能连解释本身都看不懂——不值得试图覆盖所有人。

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

【讨论】：

我绝对同意当代码更改时 cmets 经常被忽略。好点子！
您应该保证通过代码审查或结对编程来更新 cmets。
+1 推荐清洁代码。
@MarkJ 我更喜欢编写不需要 cmets 的代码，而不是花费额外的精力让它们保持最新。
“当代码和 cmets 不一致时，他们可能都错了”

【解决方案3】：

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

【讨论】：

【解决方案4】：

要遵循的最重要的事情是：

为您的变量、方法、类...提供有意义的名称
以清晰的职责编写类/模块
不要混淆不同级别的代码（不要在一个方法中进行位移和高级逻辑）

【讨论】：

【解决方案5】：

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

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

【讨论】：

【解决方案6】：

我个人觉得完全没有 cmets 和过多的评论一样糟糕。你只需要找到合适的平衡点。关于使用长描述性名称，我总结了这一点：read this 另请阅读 Kernighan 和 Pike 的长名称。

【讨论】：

【解决方案7】：

你需要遵守一定的规则。

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

【讨论】：

如果您打算使用设计模式，那么是的，看在上帝的份上，请相应地命名。但我不相信使用设计模式本身对代码的可读性有好处——尤其是在 Ruby 中。