是否有代码/注释比率被认为是良好(不良)代码运行状况的标志？

我们能举一些被认为编码正确的开源项目及其各自的评论比例的例子吗？

(我意识到，没有哪个比率对每个项目都是"正确的"，并且很可能会有烂摊子项目表现出这一理论黄金比率。不过...

解决方案

它可以变化很多。例如，我们可以编写出色的代码，以至于注释只是浪费时间。

我们需要足够的注释，因此几个月后，我们可以查看代码，阅读注释，然后轻松地从上次停下来的地方继续学习。如果不需要代码的真实故事，请不要编写。

我们认为有必要的地方应该有评论。不多也不少。

再次查看代码后，请休息六周以上，然后注释一下我们可能不理解的部分

没有黄金分割率。注释的数量在很大程度上取决于代码的固有复杂性。如果我们只是编写CRUD应用程序，则可能不需要很多注释。如果我们正在编写操作系统或者RDBMS，则可能需要添加更多注释，因为我们将执行更复杂的编码，并且需要使其变得更明确地说明为什么要执行自己的工作。

没有比代码高的注释率的事情了。在过去，有些人认为我们需要在每个函数的开头添加注释以说明其功能。

但是，随着现代语言的出现，代码几乎可以自我记录。这意味着在代码中留下注释的唯一原因是解释奇怪的决定是从哪里来的，或者是帮助理解一个非常复杂的主题。

注释应该非常稀有且有价值，几乎总是表示"为什么"而不是"如何"(例外是"如何"很复杂，并且很难从代码中辨别出来)。

每个注释都暗示我们可能需要重构以使代码的意图更清晰。每条评论撰写后都有可能过时。

在我们的xUnit.net项目中，除了XML注释外，几乎没有其他注释，但是有些人似乎发现代码清晰易读。 :)

抱歉，没有经验法则。每种情况下，框架和库都需要更多注释，因为程序员将是客户，并且没有时间每次需要调用方法时都读取代码。

我们正在编写/阅读代码的项目需要较少的注释，应尝试提高代码的可读性，而不是注释/代码的比例。

亲切的问候

没有"黄金比例"。这取决于语言和编写方式。代码表现力越强，可以自我记录的内容就越多-因此所需的注释也就越少。这是流利的界面的优势之一。

我会尽量减少评论。代码应该是自解释的，而源代码往往会更改注释，而注释几乎总是作为错误的解释而留下。

我认为每个人都可以同意，0注释通常可以视为未成文的代码。请记住，即使是最自我记录的代码也只能记录其中的内容。永远不会有意地遗漏，优化，尝试和丢弃等内容。基本上，在源文件中，我们总是会需要英语，或者我们肯定会忽略重要的警告和设计决策。

我对你们倡导的这些声音原则(到目前为止我完全同意)如何转换为代码统计感兴趣。特别是，哪些开源项目被认为是有据可查的(而不是过度记录)，那里的评论比率是多少。

黄金代码/评论比率是

• 需要注释以使自己想起编码时的想法
• 需要注释来提醒其他人在编码时要记住的事情
• 客户愿意支付的评论(因为好的评论会花费时间)
• 由于工作安全，开发人员对产生混淆代码的兴趣(如果他或者她在为开发人员可以摆脱它的公司工作)

这也说明了为什么每个项目和每个团队的比率都不同。

我有一个非常简单的经验法则：如果在编写某些代码(例如，函数或者复杂的循环等)时需要停下来思考15秒以上，那么该代码需要注释。

对我来说真的很好。下次当我们或者我们对整体代码库有一定了解的人员遇到该段代码时，他将立即知道为什么这样做是这样做的。

我们不能强制使用固定的代码/注释比率，否则我们将遇到带有噪声的代码，例如：

// Add one to i
i++;

这只是使代码模糊。

相反，请查看代码的复杂性并查看我们需要解释的内容，即小巧的逻辑，为何使用某些幻数，关于传入格式存在哪些假设等。

开启维护人员的思维定式，考虑一下我们希望看到的与我们刚刚编写的代码有关的内容。

HTH。

干杯，

抢

我的规则是：如果需要说些什么而无法编写代码来表达它，那么我们可以写一个注释。否则，如果代码可以表达想法，那么我们必须在代码或者其测试中表达想法。

如果遵循此规则，则只有在处理硬件或者操作系统中一些不太明显的问题时，或者当最明显的算法不是最佳选择时，代码才需要注释。这些是"这很奇怪，因为"注释，实际上只是一种应对机制。大多数时候，代码中的注释实际上只是道歉，没有以更明显的方式编写注释，因此应避免此类注释，然后将其删除。

即使是良好的评论也会随着时间的流逝而成为谎言，因此，诸如评论之类的不可执行，不可测试的地方的信息也应引起怀疑。同样，答案是首先消除评论，然后删除它。

我的理想比率是零。但是，世界并不理想，因此，在没有其他方法可以传达重要思想时，我会接受评论。

IMO有3种用途：

• 解释为什么代码会做什么
• 记录模块的接口
• 解释为什么不采用其他处理大量逻辑的方法

如果代码执行的基本操作足以使原因清楚，那么在大多数领域中，大多数情况下应该如此，那么逻辑中的注释应该最少，甚至没有任何注释。注释绝对不能解释其含义(例如，可能有例外，例如该函数是Bar出版物中解释的Foo算法的实现)。如果我们需要解释自己在做什么，那就做得不好。

LOC / LOcomment = yearsofexp / 5

在Steve McConnells()的《 Code Complete》一书中，对代码注释进行了精彩的讨论(我拥有第一版，但我相信现在是第二版的链接文本)

总而言之，它强调了其他答案很少出现的问题，并说明了为什么不能重构变量和方法名称以替换注释，而大多数IDE都提供某种类型的intellisense(或者我曾经听过Don Box由于其敏捷性而将其形容为intellicrack)当更长或者更清晰的版本可以更清楚地传达其意图时，没有理由截断变量/方法名称

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

带有"无评论"注释的隐含"我的意思"命令？

不得不修复另一个程序员的代码的人将说出尽可能多的注释。旧代码的最大问题是："我们看到了代码的功能。我们看到了问题所在。但是我们不知道程序员为什么这样写。"

要了解错误，我们需要了解以下内容：

• 代码应该做什么(而不是代码做什么)以及原因。
• 每个职能的契约。例如，如果存在NullPointerException，那么错误在哪里？在函数中还是在调用函数中？
• 在每个Hack上都描述了如何重现该问题(语言版本，操作系统，操作系统版本)。例如，我们有许多针对旧Java VM的黑客，这些黑客不再受支持。但是我们不确定是否可以删除它，因为我们不知道如何复制它们。

我们的比率为2-3％，这太少了。我认为10％适用于大型或者长期存在的项目。

如果我们需要一些有关不同语言的评论比率的真实世界数据，请查看Ohloh。

例如，我们可以查看Linux内核源代码的各种指标。

注释不仅解释了代码，而且还指导调试器寻找正在执行某些功能的代码。

检索客户的订单历史记录或者计算敌方玩家是否可见可能要花费数十行代码，甚至是专业的程序员也可能要花费几分钟才能确定其作用。如果说"检索客户的订单历史记录"，则调试器如果知道订单历史记录不是问题，则根本不会研究该代码。

没有这样的比例。

通常，仅在某些情况可能确实不清楚的情况下(例如，

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

另一方面，如果我们要将代码出售给某人，它将需要尽可能多的注释。成像销售没有评论的3D引擎或者其他一些游戏中间件。当然，API文档等也是此类中间件的重要组成部分，但是注释良好的代码也很有价值。诸如"向i添加1"之类的内容仍然过于垃圾，但是诸如" CreateDevice()将首先检查DirectX 10是否可用，如果没有则回落到DirectX 9设备"之类的东西，即使对从代码中看到。

通常，与我们出售的代码相比，内部代码的注释通常少得多，但可能会有例外。

我喜欢使用注释来注释代码，以确保代码易于阅读并且具有信息量大的变量。话虽这么说，但我想尽可能地编写每一行代码，使其尽可能多地包含注释。在阅读注释之前或者在做错错误之前，我们应该能够对代码的工作有很强的了解。

我认为我认为模棱两可或者应该解释的所有内容。通常，我过度评论。为什么？因为我们永远不知道谁将处理代码。我喜欢想象这样一种情况，他们用猴子代替了一半的团队，猴子只知道当他们在一行上按Enter键时，他们会得到一根香蕉。因此，如果他们至少学会阅读，他们不会不阅读我的注释就不会改变我的逻辑。

案例和要点：

// Delete the helloworld file
exec("rm -f helloworld.txt")

不会更改为：

exec("rm -rf /")

我知道不太可能，但是即使是一些优秀的开发人员也知道更改逻辑，因为它看起来不正确，也不是因为存在错误或者需求变更。

我不认为任何人都可以给我们提供数字，但是头文件中的数字应该比源文件中的数字高得多。

我希望类的头文件通过包含该头文件来记录可公开访问的所有类/函数/等。记录一个原型仅是一行的函数可能要花很多行(不行，仅为函数及其参数选择好名字就可以了，但通常不是)。每行代码的三行注释不会过多。

对于实际代码，它将低得多。我不同意极端主义者的看法，他们认为我们应该以零评论为目标，但是如果我们认为自己需要评论，可以肯定的是，首先应该考虑是否可以使代码更清晰。

在3％至9.5％之间，或者多或者少