评论你的代码的重要性

Question

你如何解释你的团队配合评论他们写的代码的重要性？我知道一些编写片段式评论的编码员，而其他人会留下很多预期的内容，当你阅读评论时你期望什么？

Answer 1

如果您正在编写的语言不是人类可读的，我建议您使用非常详细的方法和过程级别注释。

如果您正在编写的语言是人类可读的（C＃，VB等），我建议您在方法级别使用稍详细的注释并在过程级别使用最少的注释。

Answer 2

有一些最低：

1. 所有的函数和类应该评论
2. 的try/catch和异常处理是更好地加以注释
3. 常量硬代码编码应该是绝对
4. 虚拟物体和虚拟类以及TO-DO部分应该被注释
5. 当您从URL获取代码时，应该在评论中引用地址以便进一步考虑n和侵犯版权的问题
6. 还承诺到版本控制系统应该有很好的注释

虽然意见应保持在最低限度，也没有必要评论for循环定义时，很明显， 我通常为我的程序员设置基本规则，当它定义良好时，他们坚持使用它

Answer 3

在编写不直观的代码时编写注释。实际上没有理由评论只是迭代数组的方法，但是当您修复一个错误或必须一起破解某个问题才能解决问题时，最好有一个注释，以便您可以在6个月后快速了解该代码（以及不意外撤消它）。

Answer 4

你是什么意思的评论代码？ 实际的代码或函数标题？

如果你真的在谈论代码，这是一个失败的原因。你需要让他们编写可读的代码并将其分解成有意义的块。评论不好的代码并没有把它变成好的代码，它只是留下不一致的混乱。对于标题文档，你必须让他们捕捉重要的东西（例如，惊喜，指令）并妥协一些微不足道的事情（列出所有参数，重复签名的功能）。人们讨厌记录函数，因为大部分工作都花在编写琐碎的文本上，这些文本几乎影响了你的智能（例如，getHandleToFile（），“这会得到文件的句柄”）。由于实际上有比预期更少的重要细节，因此他们会感到惊喜，并且将更有可能将投入投入到这些特定情况中。

Answer 5

• 在方法和类中包含文档生成注释。
• 不要评论每一行。
• 如果您正在做一些预期的或代码中不明显的事情，请解释说明原因。

Answer 6

我认为如果你正在编写其他人可能会有一天需要遵循的代码，那么谨慎地留下关于正在做什么的好评。如果你只是为自己写点东西，那么倾向是很小的，或者根本没有。这就是说，我已经有了“不那么奢侈”的必须返回到我8年前写的代码，并没有充分评论，用我不再使用的语言（ASP类），我可以告诉你，我希望我已经留下了更多评论！

Answer 7

在评论中最重要的事情是说实话。我一直在调查一个错误的次数，仅仅是为了找到一段“不太明显”的代码，还有一条评论说它应该和它所做的相反。谁赢？你决定...

在一个相关的说明，任何比它正在记录的部分更长的评论是通常太长。

Answer 8

最好的评论总是简洁，用几句话。它应该说在代码中不明显。我看到一些明显的人，因此无用的评论，如：

if x==0 //if x equals 0 then... 

哦真的吗？！这只是“污染”了代码，因为除非你正在学习如何编程，否则它是无用的。

即使代码只是你的，你应该写评论，就好像你正在与另一个完全不知道它的程序员分享它。通过这种方式，您可以确保您始终能够理解它，并且长期来说，如果有人出现并选择了该代码，那么该人员将能够理解并扩展/使用它。

我看到评论作为可重用性的提升。与其他程序员一样，我期望通过一个简单而简明的评论来完整理解代码块。

Answer 9

我尝试评论我的大部分公共方法和类，并且在那些注释中，您可以阅读该方法的作用，参数的含义以及输出的内容。

我也有时会在我的方法中放置注释，但是，我不评论我在做什么，但为什么我这样做。