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

Question

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

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

两个目标如何在不相互干扰的情况下完成,同时又是一项快速的任务,而不是花费大量的编码时间？

Answer 1

我能给你的最好建议是:

不要评论坏代码; 重写它!

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

罗伯特·马丁斯清洁代码是一本帮助我创建更好代码的书.如果您还没有看过,请这样做.让公司的所有开发人员都阅读它.

祝好运.

Answer 2

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

//只要代码不足以完全理解正在发生的事情,就可以使用注释来评论代码.这些评论的读者可能是将来三个月或其他开发人员维护您的代码.您可以使用特殊注释,例如TODO或BUGBUG标记您必须重新访问的代码.