什么是黄金代码/评论比例？

Question

您认为代码/评论比率是否代表良好（不良）代码健康状况？

您能举例说明被认为编码良好的开源项目及其各自的评论比例吗？

（我意识到每个项目的比例都不是“真实的”，而且很可能是那些表现出理论黄金比例的糟糕项目。还是......）

Answer 1

评论应该是非常罕见和有价值的，几乎总是表达“为什么”而从不表达“如何”（例外情况是如何复杂且不易从代码中辨别出来。）

每条评论都暗示您可能需要重构以使代码的意图更清晰。每一条评论都有可能在写完后立即过时。

除xUnit.net project中的XML评论外，我们几乎没有任何评论，但some people似乎发现代码清晰易读。 ：）

Answer 2

任何需要修改其他程序员代码的人都会说尽可能多的评论。旧代码的一个大问题是：“你看到代码的作用。你看到这就是问题所在。但是你不知道为什么程序员会这样写它。”

要了解您需要知道的错误：

• 代码应该做什么（不是代码的）以及原因。
• 每个职能的合同。例如，如果存在NullPointerException，那么bug在哪里？在函数或调用函数中？
• 每个Hack都描述了如何重现问题（语言版本，操作系统，操作系统版本）。例如，对于不再支持的旧Java VM，我们有许多黑客攻击。但我们不确定是否可以删除它，因为我们不知道如何重现它们。

我们的比率为2-3％，太少了。我认为10％对大型或长期项目有利。

Answer 3

评论不只是解释代码 - 它们还指导正在寻找代码片段的调试器。

检索客户的订单历史记录或计算敌方玩家是否可见可能需要几十行代码，即使是专业程序员也可能需要几分钟才能确定它的作用。如果他知道订单历史记录不是问题，则说明“检索客户的订单历史记录”的注释允许调试器根本不调查该代码。

Answer 4

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

您正在编写/阅读代码的项目需要较少的评论，并应尝试提高代码可读性而不是评论/代码比率。

亲切的问候

Answer 5

我评论一切我认为含糊不清或应该解释的内容。通常，我过度评论。为什么？因为你永远不知道谁会对你的代码起作用。我喜欢想象一种情况，他们用猴子代替团队的一半，只知道当他们按下线路时，他们会得到一根香蕉。因此，如果他们至少学会阅读，他们不会在不先阅读评论的情况下改变我的逻辑。

案例和观点：

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

不会改为：

exec("rm -rf /")

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

Answer 6

我认为每个人都同意0条评论通常可以被视为子文档代码。请记住，即使是最自我记录的代码也只能记录那里;从来没有故意遗漏，优化，尝试和丢弃等等。基本上，你的源文件中总是需要英语，或者你必须遗漏重要的警告和设计决定。

我感兴趣的是你们这些声音原则如何提倡（到目前为止我完全同意）转化为代码统计。特别是，哪些开源项目被认为是好的（没有过度）记录，以及那里的评论比例。

Answer 7

我有一个非常简单的经验法则：如果你需要在编码某段代码（例如，函数或复杂循环等）时停止并思考超过15秒，那么这段代码需要评论。

对我来说真的很好。下次，或者您对整个代码库有所了解程度的人遇到这段代码时，他会立即看到为什么按照完成的方式完成。

Answer 8

LOC / LOcomment = yearsofexp / 5

Answer 9

我的规则是这样的：如果有需要说的话并且代码可以 而不是来表达它，那么你可以写一个评论。否则，如果代码可以表达这个想法，那么你必须在代码或其测试中表达这个想法。

如果您遵循此规则，那么您的代码在处理硬件或操作系统中的某些不明显问题时，或者当最明显的算法不是最佳选择时，应该只需要注释。这些是“这很奇怪，因为”评论，而且实际上只是一种应对机制。大多数时候，代码中的注释实际上只是抱歉不以更明显的方式编写它，这样的注释应该被排除然后删除。

即使好的评论经常会随着时间的推移而变成谎言，因此在不可执行的，不可测试的地方（如评论）中的信息也会被怀疑。同样，答案是首先删除评论，然后删除它。

我的理想比例为零。然而，世界并不理想，所以当没有其他方式来传达一个重要的想法时，我会接受评论。

Answer 10

那里应该有你认为必要的评论。不多也不少。

在再次查看代码

后，评估6或多周休息后您可能不理解的部分

Answer 11

我尽量保持评论。代码应该是自我解释的，虽然源代码往往会改变，但评论几乎总是留在错误的解释中。

Answer 12

黄金代码/评论比率是

的交集

• 评论需要提醒自己编码时想到的事情
• 评论需要提醒其他人在编码时记住的事情
• 评论您的客户愿意为此付费（因为好的评论需要花费时间）
• 由于工作安全（如果他或她为开发人员可以逃脱的公司工作），开发人员有兴趣制作混淆代码。

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

Answer 13

我不认为任何人都可以给你数字，但是头文件中的数字应该高于源文件。

我希望类的头文件能够通过包含该头文件来记录所有可公开访问的类/函数/等。这可能是很多行来记录一个函数，其原型是单行（不，只是为函数选择好名称，它们的参数是不够的 - 它可以，但通常不是）。每行代码的三行注释都不会过多。

对于实际代码，它会低得多。我不同意那些认为你应该针对零评论的极端分子，但当然如果你认为你需要评论，你应该先考虑是否可以使代码更清晰。

Answer 14

没有黄金比例。注释的数量在很大程度上取决于代码的固有复杂性。如果您只是编写CRUD应用程序，则可能不需要大量注释。如果您正在编写操作系统或RDBMS，您可能需要更多注释，因为您将进行更复杂的编码，并且需要更明确地说明为什么要执行您正在执行的操作。< / p>

Answer 15

如果您想了解不同语言的评论比率的实际数据，请查看Ohloh。

例如，您可以查看Linux内核源代码的various metrics。

Answer 16

我不得不说我来这里寻找每1行代码约2条评论的答案。即使这是夸大其词也是正确的方向！相反，我看到人们建议处理像松露或其他稀有商品的评论。从学术界的一个特殊角度来看，代码质量很低，版本控制的使用甚至更少，然后松露我会敦促任何人写尽可能多的评论，甚至反对你自己判断评论是否100％必要。

评论让你的生活变得更轻松，因为你有机会思考，在写这篇文章时我到底在想什么！

Answer 17

介于3％和9.5％之间，或多或少

Answer 18

它可能会有很大差异。例如，你可以编写如此好的代码，以便评论只是浪费时间。

你需要足够的评论，所以几个月之后你可以查看你的代码，阅读评论，然后只需从中断的地方拿起，不费吹灰之力。如果不需要代码的生活故事，请不要写它。

Answer 19

我喜欢使用注释来注释我确保易于阅读并具有信息变量的代码。话虽这么说，我想尝试编写每行代码，如果可能的话，作为评论提供信息。在阅读评论之前，您应该能够对代码所做的事情有一个非常强烈的要点，或者您做错了。

Answer 20

没有这样的比例。

通常情况下，只有在某些内容可能真的不清楚的情况下才会出现评论，例如

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

另一方面，如果您向某人销售代码，则需要尽可能多的评论。想象出售3D引擎或其他没有评论的游戏中间件。当然，API-Documentation等也是这类中间件的重要组成部分，但好的注释代码也是有回报的。像“添加1到i”这样的东西仍然太垃圾了，但像“CreateDevice（）之类的东西会首先检查DirectX 10是否可用并且如果没有则返回到DirectX 9设备”，可能真的很有帮助，即使它对于从代码中看。

通常，内部代码通常比您销售的代码评论少得多，但可能会有例外情况。

Answer 21

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

隐含的“Do Do I Mean”命令带有“无评论”评论？

Answer 22

史蒂夫麦克康内尔（Steve McConnells）书中的代码评论（Code Complete）（我有第一版，但我相信现在是第二版link text）

总结一下，它强化了其他答案所说的内容 - 应该是罕见的，并描述为什么不是如何 - 如果你可以重构变量和方法名称来替换那些应该被预先设定的评论 - 大多数IDE提供某种智能感知（或者我曾经听过Don Box将其描述为 - intellicrack由于其adictivness）没有理由在更清晰的版本更清楚地传达其意图时截断变量/方法名称

Answer 23

评论有3种用途，IMO：

• 解释为什么代码执行的操作
• 记录模块的界面
• 解释为什么没有采用其他方法来处理一大块逻辑

如果代码正在做一些基本的事情，为什么是明确的，这应该是大多数域中的大部分时间，那么逻辑中的注释应该是最小的...甚至接近无。注释永远不应该解释 what （可能有例外，例如，该函数是Foo算法的实现，如Bar Publication中所述）。如果你需要解释你正在做什么，你做得很差。

Answer 24

你不能强制要求固定的代码/注释比率，否则你最终会得到带有噪音的代码：

// Add one to i
i++;

这只会使代码浮云。

相反看看代码的复杂性，看看你需要解释什么，即squirelly逻辑，为什么使用某些幻数，有关传入格式的假设等等。

启用您的维护者思维模式，并考虑您希望看到的关于您刚才编写的代码的描述。

HTH。

欢呼声，

罗布

Answer 25

没有“黄金比例”。这取决于语言和你写它的方式。代码越具有表现力，就越能自我记录 - 因此您需要的评论就越少。这是流畅界面的一个优点。

Answer 26

对代码比率没有好评。在过去，有些人认为你需要在每个功能的头部发表评论，解释它的作用。

然而，随着现代语言的出现，代码几乎是自我记录的。这意味着在代码中留下评论的唯一原因是要么解释奇怪的决定来自哪里，要么帮助理解一个非常复杂的主题。