How should comments for interface and class method

问题:

I ran into this dilemma when working on an ASP.net web application using Web Client Software Factory(WCSF) in C#, and the same could apply to other platform and languages. My situation is like this:

I am defining an IView interface for each web page/user control based on WCSF paradigm, then have the page class implement the IView interface, basically implementing each of the methods defined in the interface. When I tried to add xml-documentation on the method level, I found myself basically repeating the same comment content for both interface method, and its counter-part in the implementing class.

So my question is: should there be some substantial difference between the documentation content on the interface method and corresponding class method? Should they be emphasizing on different aspect or something?

Somebody told me that the interface method comment should say "what" the method is supposed to do, and the class method comment should say "how" it does it. But I remember reading somewhere before that the method level comment should only say "what" the method is supposed to do, never the implementation detail of the method, since the implementation should not be a concern for method users and it might change.

回答1:

Personally, I think these comments should be the same - both should say "what the method is going to do", in your terms.

There is no reason for XML comments to mention implementation details. The one exception, potentially, would be to mention potential side effects (ie: this method may take a long time), but I personally would do that in the <remarks> section of the XML doc comments.

回答2:

Call me a nut but I'd use a descriptive name for the method and call it a day (no comments for either). I might add comments to the implementation if something about it is surprising or why its there is nonobvious.