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

是否有代码/注释比率,您认为是良好(坏)代码健康的标志？

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

(我意识到每个项目的比例都不是"真实的",并且很可能是那些表现出理论黄金比例的糟糕项目.仍然......)

1> Brad Wilson..：

---

评论应该是非常罕见和有价值的,几乎总是表达"为什么"而从不表达"如何"(例外情况是如何复杂且不易从代码中辨别出来).

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

除了我们的xUnit.net项目中的 XML注释之外,我们几乎没有任何评论,但有些人似乎发现代码清晰易读.:)

---

-1.对于那些试图阅读其他人的代码的人,以及他们试图阅读的代码中的评论"稀有且有价值"将花费更多时间来尝试理解代码而不是阅读评论并对某些事情做好事. .

---

这是灾难的秘诀.评论应该经常和公然.评论的目的是显示*为什么*.代码本身显示了正在发生的事情.但它从未说明原因.未注释的代码是死代码.

---

不同意100%.如果代码更改,注释将变得过时,如果发生这种情况,则不要过于懒惰并更新注释.无论谁认为通过阅读代码而不是阅读*描述正在发生的事件的实际句子来更容易理解正在发生的事情,都应该尝试浏览Fortran中遗留代码的页面.

2> Horcrux7..：

---

谁必须修改另一个程序员的代码,就会尽可能多地发表评论.旧代码的一个大问题是:"你看到代码的作用.你看到这就是问题所在.但是你不知道为什么程序员会这样写."

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

什么应该的代码做(没有什么代码的功能),以及为什么.

各项职能的合同.例如,如果存在NullPointerException,那么bug在哪里？在函数或调用函数中？

在每个Hack上都描述了如何重现问题(语言版本,操作系统,操作系统版本).例如,对于不再支持的旧Java VM,我们有许多黑客攻击.但我们不确定是否可以删除它,因为我们不知道如何重现它们.

我们的比例为2-3%,太少了.我认为10%对大型或长期项目有利.

3> marcospereir..：

---

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

您正在编写/阅读代码的项目需要较少的注释,并应尝试提高代码可读性而不是注释/代码比率.

亲切的问候

4> DJClayworth..：

---

注释不只是解释代码 - 它们还指导调试人员正在寻找执行某些操作的代码.

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

5> willasaywhat..：

---

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

案例和观点:

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

不会改为:

exec("rm -rf /")

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

6> Assaf Lavie..：

---

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

我感兴趣的是你们所倡导的这些声音原则(到目前为止我完全同意)转化为代码统计.特别是,哪些开源项目被认为是好的(没有过度)记录,那里的评论比例是多少.