7

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.

hongliang
  • 615
  • 4
  • 10

2 Answers2

8

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.

Reed Copsey
  • 554,122
  • 78
  • 1,158
  • 1,373
  • This is the answer I was actually afraid of :), but I guess you are right. I get worn quickly repeating the same content in both places. Copy-n-paste helped to speed it up, but the fact I am doing that scrares me... – hongliang Mar 05 '10 at 19:45
  • 1
    @hongliang: If you're implementing an interface, get a copy of GhostDoc - it will let you use a single key to fill in XML doc comments for the implementing class, and copy the comments from the interface. Very slick: http://submain.com/products/ghostdoc.aspx – Reed Copsey Mar 05 '10 at 19:57
  • Wow! That is exactly what I would like. Thanks! – hongliang Mar 05 '10 at 20:08
  • @ReedCopsey Hi Reed, I didn't know about GhostDoc so I went ahead and installed it for a test. Still reading the manuals/forums on what I can do with it? How do you copy comments from the interface to the class methods that does the implementation? Is it possible in the free version or do I need to buy Pro? – Filip Oct 13 '11 at 02:07
  • @Filip When you doc the implementation, it should just grab the interface comments automatically (even in free)... – Reed Copsey Oct 15 '11 at 17:52
5

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.

Frank Schwieterman
  • 24,142
  • 15
  • 92
  • 130
  • 7
    I actually disagree pretty strongly. Commenting methods (with short, meaningful comments) using XML doc comments is very valuable, especially if it's an API that may be used by other people... There's no substitute for the meaningful messages in intellisense you get from xml doc comments. – Reed Copsey Mar 05 '10 at 19:32
  • Thanks. I agree that name should be descriptive, which will make comments seemingly redundant. Still, my own experience tells me sometimes, there is only that much you can say with a name---unless you don't mind ridiculously long names with "When"s and "If"s in it. – hongliang Mar 05 '10 at 19:35
  • 1
    If the caller must be concerned with all the when/ifs of how a method its calling is implemented, thats design feedback your objects have too much coupling. – Frank Schwieterman Mar 05 '10 at 19:41
  • You are right. What I really meant is the auxiliary words in general, which might not fit into method names, but necessary to convey meanings. For example, there IS extra useful information in "Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources." than "Dispose", would you agree? :) – hongliang Mar 05 '10 at 20:17
  • I think using Dispose is preferred because most developers will recognize what to do with it (assuming you're implementing IDispose) – Frank Schwieterman Mar 06 '10 at 02:55
  • Yes, I was talking about IDispose.Dispose(). The "Perform..." sentence is from .NET framework comment for IDispose.Dispose() method. I used it as an example to show comments can convey more information to users, thus useful, even if the method name itself, "Dispose" here, is already descriptive. – hongliang Mar 06 '10 at 14:37
  • I'll have to agree with @reed-copsey on disagreeing with you. I look at comments from my old projects and I find it easier to remember what the method does. – Joel May 08 '13 at 09:58