3

你如何解释你的队友对他们编写的代码进行注释的重要性？我知道有些程序员写的是情节评论，而另一些人则留下了很多期待，当你阅读评论时你会期待什么？

4

9 回答 9

3

有一些最低要求：

  1. 所有函数和类都应该注释掉
  2. Try/Catch 和异常处理最好被注释掉
  3. 代码中硬编码的常量绝对应该是
  4. dummy objects 和 dummy classes，以及 TO-DO 部分应该被注释掉
  5. 当您从 URL 中获取代码时，应在评论中引用该地址以供进一步考虑和版权侵权问题
  6. 对版本控制系统的提交也应该得到很好的评论

虽然注释应该保持在最低限度，当一个 for 循环定义很明显时不需要注释，我通常为我的程序员设置基本规则，当它定义良好时他们会坚持它

于 2009-01-17T22:02:38.990 回答
3

最好的评论总是简明扼要，几句话。它应该说明代码中不明显的内容。我看到很多人发表了明显且因此无用的评论，例如：

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

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

即使代码只是你的，你也应该写注释，就好像你要与另一个完全不知道它的程序员分享它一样。这样你就可以确保你永远理解它，并且从长远来看，如果有人出现并拿起那个代码，那个人将能够理解它并扩展/使用它。

我将评论视为可重用性的提升。我希望像其他所有程序员一样，通过一个简单、简洁的注释来完全理解一段代码。

于 2009-01-17T22:09:35.073 回答
2

在编写不直观的代码时写注释。确实没有理由评论仅迭代数组的方法，但是当您修复错误或必须一起破解某些东西以解决问题时，最好发表评论，以便您可以在 6 个月后快速理解该代码（并且不要意外撤消它）。

于 2009-01-17T22:02:41.390 回答
2

注释代码是什么意思？实际代码，还是函数头？

如果您实际上是在谈论代码，那将是一个失败的原因。您需要让他们编写可读的代码并将其分解成有意义的块。注释不好的代码并不能使它成为好的代码，它只会留下不一致的混乱。

至于标头文档，您必须让它们捕获重要的事情（例如，惊喜、指令）并就琐碎的事情妥协（列出所有参数，重复签名所做的事情）。人们讨厌记录函数，因为大部分精力都花在编写几乎侮辱您的智力的琐碎文本上（例如，在 getHandleToFile() 上，“这会获取文件的句柄”）。由于实际上存在的重要细节比人们预期的要少得多，因此他们会感到惊喜，并且更有可能在这些特定情况下投入精力。

于 2009-01-17T22:02:42.577 回答
1

我认为，如果您正在编写其他人可能有一天必须遵循的代码，那么谨慎地对正在做的事情发表好的评论是明智的。如果您只是为自己写一些东西，那么倾向于留下最少或根本没有。话虽如此，我已经“不那么奢侈”了，不得不回到我 8 年前写的代码并且没有充分评论，用一种我不再使用的语言（ASP 类），我可以告诉你，我希望我留下更多评论！

于 2009-01-17T22:03:17.130 回答
1

我尝试评论我的大多数公共方法和类，在这些评论中，您可以阅读该方法的作用、参数的含义以及（如果适用）输出将是什么。

我有时也会在我的方法中添加评论，但是，我不会评论我在做什么，而是为什么我要那样做。

于 2009-01-17T22:45:08.233 回答
0

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

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

于 2009-01-17T21:58:24.207 回答
0
  • 包括对方法和类的文档生成的注释。
  • 不要评论每一行。
  • 如果您正在做一些预期的事情或代码中不明显的事情，请在评论中解释原因。
于 2009-01-17T22:03:09.143 回答
0

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

在相关说明中，任何比其记录的部分更长的评论通常太长。

于 2009-01-17T22:03:36.287 回答