接口和类方法的注释应该如何不同

Question

在使用C#中的Web客户端软件工厂(WCSF)处理ASP.net Web应用程序时,我遇到了这种困境,同样适用于其他平台和语言.我的情况是这样的:

我正在为基于WCSF范例的每个网页/用户控件定义一个I View界面,然后让页面类实现I View界面,基本上实现界面中定义的每个方法.当我尝试在方法级别添加xml文档时,我发现自己基本上重复了接口方法的相同注释内容,以及它在实现类中的反向部分.

所以我的问题是:接口方法的文档内容和相应的类方法之间是否存在一些实质性的区别？他们应该在不同方面强调什么？

有人告诉我,接口方法注释应该说该方法应该做什么,而类方法注释应该说"它是如何做的".但是我记得在之前的某处读过方法级别注释应该只说"该方法应该做什么",而不是方法的实现细节,因为实现不应该是方法用户的关注,它可能会改变.

Answer 1

就个人而言,我认为这些评论应该是相同的 - 两者都应该用你的术语说"方法将要做什么".

XML注释没有理由提及实现细节.可能的一个例外是潜在的副作用(即:此方法可能需要很长时间),但我个人会<remarks>在XML文档注释部分中这样做.

Answer 2

你可以说我是个疯子，但我会为该方法使用一个描述性名称，然后就到此为止（两者都没有评论）。如果有关它的某些事情令人惊讶或者为什么它不明显，我可能会对实现添加评论。