评论代码C＃visual studio最佳实践

Question

我正在寻找一个相当随意的答案，所以这可能更像是一个讨论。我想知道在visual studio中评论我的C＃代码的最佳做法是什么。现在我正在使用三重///来生成xml并使用sand castle来构建一个chm或html文件。但我的问题是我使用代码注释有两个原因：

1. 当其他开发人员使用我的代码时，他们可以阅读文档，包括intellisence和chm。或者html文件。
2. 但我也用评论作为提醒自己。所以当我半年后回来时，我能记住一些复杂的方法。

如何在不干扰彼此的情况下实现两个目标，同时又是一项快速的任务，而不是花费大量的编码时间？

Answer 1

我能给你的最好建议是：

  

不要评论不良代码;改写它！

如果方法非常复杂，大多数时候你做错了（并不总是，但总是非常接近）。编写可读代码很难，但需要付出代价，因为写一些好的评论，你（或你的大学）一年后会理解的很难（甚至可能更难）。明确方法是通过在较小的命名方法中使用非常清晰的变量名来破解方法。

一本帮助我创建更好代码的书籍是Robert Martins Clean Code。如果您还没有看过，请这样做。让公司的所有开发人员都阅读它。

祝你好运。

Answer 2

使用///条评论来记录您的公开API和受保护的API。使用<remarks>来描述应如何使用API​​。这些评论的读者是使用您的代码的其他开发人员。

如果单独的代码不足以完全理解正在发生的事情，请使用//条评论代码。这些评论的读者可能是将来三个月或其他开发人员维护您的代码。您可以使用TODO或BUGBUG等特殊评论标记您必须重新访问的代码。

Answer 3

我将两种评论样式 - ///合并为关于类，方法等的“公开”文档，并将//合并为“私人”评论，供我自己或跟随我阅读的编码人员使用。