什么是黄金代码/评论比?[关闭]

Question

有一个代码/评论比，你认为是一个迹象的良好(糟糕)代码的健康？

你能给的例子开源项目，都被认为是很好的编码及其各自的评论比?

(我意识到，没有比"真正"对于每一个项目，并很可能蹩脚的项目表现出这种理论上的黄金比例。还是...)

Answer 1

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

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

除了 xUnit.net项目中的XML注释，我们几乎没有任何评论，但某些人似乎发现代码清晰易读。 ：）

Answer 2

谁有解决码从另一个程序员会说 尽可能多的意见，尽可能.最大的问题与老码是："你看到什么代码。你看，这就是问题所在。但你不知道为什么该程序编写的，它是这样的。"

了解一个错误，你需要知道的：

• 什么样的 应该 代码做的(不 什么样的 代码)和为什么。
• 合同的每一个功能。例如，如果有一个异常然后在那里是错误?在功能或在调功能？
• 在每一个黑客是如何的问题，可再生(种语言版本，操作系统、操作系统版本)。例如，我们有许多黑客对于一个古老的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

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

Answer 14

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

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

Answer 15

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

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

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

Answer 16

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

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

Answer 17

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

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

Answer 18

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

Answer 19

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

// Add one to i
i++;

这只会使代码浮云。

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

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

HTH。

欢呼声，

罗布

Answer 20

评论有3个使用，海事组织:

• 解释 为什么 代码什么
• 文件的接口模块
• 解释为什么其他办法的一个大块的逻辑不是取

如果代码是做什么的基本足够的， 为什么 显然，这应该是大部分时间在大多数领域，然后将评论内的逻辑应该是最小的...甚至接近零。意见不应该被解释 什么样的 (可能的例外情况来说，例如，它的功能是一个执行Foo算法作为解释条公开)。如果你需要解释 什么样的 你做的，你做得很差。

Answer 21

史蒂夫·麦克康内尔（Steve McConnells）书中的代码评论有很好的讨论代码完整版（我有第一版，但我相信现在是第二版链接文本）

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

Answer 22

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

隐含的“做我的意思”带有“无评论”的命令评论

Answer 23

没有这样的比例。

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

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

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

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

Answer 24

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

Answer 25

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

Answer 26

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

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