7

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

根据WCSF范式为每个网页/用户控件定义一个I View接口,然后让页面类实现I View接口,基本上实现接口中定义的每个方法。当我尝试在方法级别添加 xml-documentation 时,我发现自己基本上为接口方法及其在实现类中的对应部分重复了相同的注释内容。

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

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

4

2 回答 2

8

就个人而言,我认为这些评论应该是相同的——用你的话来说,两者都应该说“方法将要做什么”。

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

于 2010-03-05T19:24:43.750 回答
4

叫我疯子,但我会为该方法使用一个描述性的名称,并称之为一天(两者都没有评论)。如果关于它的某些事情令人惊讶或为什么它不明显,我可能会在实现中添加评论。

于 2010-03-05T19:24:07.463 回答