如何将代码与代码保持一致？

Question

  

可能重复：
  How do you like your comments?

天儿真好，

编辑2：如果上述问题要求对评论代码提出一般性看法，我对确保代码和评论保持一致的方式更感兴趣。

我已经阅读了史蒂夫麦康奈尔的优秀代码完整书籍“Code Complete”和“Code Complete 2”，并且想知道人们是否有任何其他建议来保持评论和代码的步骤。

除了用于删除撰写评论的必要性的优秀技术之外，this blog post by Jeff about commenting并不能真正涵盖保持步骤。

我的评论口头禅可以用表达“下面的代码不能说什么”的基本思想来概括。

Answer 1

如果您在6个月后来看看您的代码，请评论您可能觉得自己不太直观的事情！

通过这种方式，你对未来的自己有所帮助（通常你会成为稍后会访问旧代码的人）以及后者可能维护代码的其他人：）

Answer 2

正如你所说，评论应该表达代码中已经不明显的东西（代码原因是什么，尝试过的方法，发现有缺陷导致代码的方式是这样的现在等等）

但从更一般的意义上讲，将代码视为逻辑上分组为相关的块。命名空间，类，方法，块，行。这些块形成应用程序的分层概述。因此，通过对块进行注释并提供概述它们的功能，您可以对代码进行汇总，并让其他人快速轻松地找到与其相关的位，理解它，然后有效地使用或修改它，并以最小的失败风险。

因此解释File.Open打开文件是没有用的。

但是解释说，一行10行代码将定位，打开，读取和存储您的应用程序的首选项，您可以保存读者必须实际读取和解码全文。简而言之，他们可以理解代码的全部目的，并知道它是否是他们需要深入研究的东西。或者如果他们希望调用代码，他们将理解它的作用以及如何使用它 - 再次，无需实际深入研究它如何实现其行为的更精细细节。

因此，在任何重要的代码块（在上述任何/所有级别）的开头都需要注释，其中摘要将保存读者必须阅读代码以便合理地理解它的作用。并且在任何需要注释代码的地方，以解释它如何或为什么做它所做的事情。

请记住，您的评论是向以前从未见过该代码的人描述代码。或者在6个月内再次访问时自己。一些精心挑选的单词可以节省小时的工作，试图解码对某些代码的完全理解。

Answer 3

当你发现自己想要包含注释时，请问自己为什么注释的部分不是自己的方法，而是使用自己的方法名称...这样你就可以通过方法名称对代码进行注释并将其分解为更小的步骤使它更清晰。