Documentation 什么'；黄金代码/注释比率是多少？ 是否有代码/评论比率，你认为是好（坏）代码健康的标志？
你能举一些被认为编码良好的开源项目的例子，以及它们各自的注释比率吗Documentation 什么'；黄金代码/注释比率是多少？ 是否有代码/评论比率，你认为是好（坏）代码健康的标志？,documentation,comments,conventions,Documentation,Comments,Conventions,你能举一些被认为编码良好的开源项目的例子，以及它们各自的注释比率吗 （我意识到没有一个比率对每个项目都是“正确”的，很可能有一些差劲的项目表现出这种理论上的黄金比率。但是…它可能会有很大的变化。例如，您可以将代码编写得非常好，以至于注释只是浪费时间 您需要足够的注释，这样几个月后您就可以查看代码，阅读注释，然后在不费吹灰之力的情况下重新开始。如果代码的生活故事不是必需的，就不要写它。应该有你认为必要的注释。不多也不少 在6周以上的休息后，当再次查看代码时，请对您可能不理解的部分进行注释。没有黄金
（我意识到没有一个比率对每个项目都是“正确”的，很可能有一些差劲的项目表现出这种理论上的黄金比率。但是…它可能会有很大的变化。例如，您可以将代码编写得非常好，以至于注释只是浪费时间
您需要足够的注释，这样几个月后您就可以查看代码，阅读注释，然后在不费吹灰之力的情况下重新开始。如果代码的生活故事不是必需的，就不要写它。应该有你认为必要的注释。不多也不少
在6周以上的休息后，当再次查看代码时，请对您可能不理解的部分进行注释。没有黄金比例。注释的数量在很大程度上取决于代码固有的复杂性。如果您只是编写CRUD应用程序，可能不需要太多注释。如果您正在编写一个操作系统或RDBMS，您可能需要更多的注释，因为您将要进行更复杂的编码，并且需要更加明确地说明您为什么要这样做。没有好的注释与代码的比率。在过去，有些人认为你需要在每个函数的头上有一个注释来解释它的作用
然而，随着现代语言的出现，代码基本上是自文档化的。这意味着在代码中添加注释的唯一原因是解释一个奇怪的决定是从哪里来的，或者帮助理解一个非常复杂的主题。注释应该是非常罕见和有价值的，几乎总是表达“为什么”，而不是“如何”（例外情况是，how很复杂，不容易从代码中识别） 每一条注释都暗示您可能需要重构以使代码的意图更清晰。每一条注释都有可能在编写后就过时
在我们的文档中，除了XML注释外，我们几乎没有任何注释，但似乎发现代码清晰易读。：）对不起，没有经验法则。每个实例的框架和库需要更多的注释，因为程序员将是客户，没有时间在每次需要调用方法时阅读代码 您正在编写/阅读代码的项目需要更少的注释，应该尝试提高代码可读性，而不是注释/代码比率
亲切的问候没有“黄金比例”。这取决于你的语言和写作方式。代码越有表现力，它就越能自我记录，因此需要的注释就越少。这是流畅界面的一个优点。我尽量将评论控制在最低限度。代码应该是自我解释的，虽然源代码倾向于更改注释，但注释几乎总是作为错误的解释保留在后面。我认为每个人都同意，0注释通常可以被视为子文档代码。记住，即使是最自我记录的代码也只能记录那里的内容；永远不要故意遗漏、优化、尝试和放弃什么，等等。基本上，在源文件中，您总是需要一些英语，或者您一定会遗漏重要的注意事项和设计决策
我对你们提倡的这些声音原则（到目前为止我完全同意）如何转化为代码统计感兴趣。特别是，哪些开源项目被认为是文档化良好（而不是过度）的，以及评论比率是多少。黄金代码/评论比率是
- 注释需要提醒自己编码时的想法
- 注释需要提醒其他人在编码时的想法
- 您的客户愿意付费的评论（因为好的评论需要时间）
- 出于工作安全考虑，开发人员对生成模糊代码的兴趣（如果他或她在一家开发人员可以逍遥法外的公司工作）
这也说明了为什么每个项目和每个团队的比率都不同。我有一个非常简单的经验法则：如果在编码某段代码（例如，函数或复杂循环等）时需要停下来思考15秒以上，那么该段代码需要注释
这对我来说真的很好。下一次，当您或您对整个代码库的理解水平达到一定水平的人遇到这段代码时，他会立即明白为什么它是这样做的。您不能强制要求固定的代码/注释比率，否则您会得到带有噪音的代码，如：
// Add one to i
i++;
Rob我的规则是：如果有什么需要说的话，而代码无法表达出来，那么你可以写一条评论。否则，如果代码可以表达想法，则必须在代码或其测试中表达想法 如果您遵循此规则，那么您的代码应该只在处理硬件或操作系统中的一些不寻常的问题时，或者当最明显的算法不是最佳选择时，才需要注释。这些都是“这很奇怪，因为”注释，实际上只是一种应对机制。代码中的大多数注释实际上只是为没有在mo中编写而道歉
LOC / LOcomment = yearsofexp / 5
0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero
// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;
// Delete the helloworld file
exec("rm -f helloworld.txt")
exec("rm -rf /")