How should comments for interface and class methods be different

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 I*View interface for each web page/user control based on WCSF paradigm, then have the page class implement the I*View 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.

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 2010-03-05 19:32:42

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 2010-03-05 19:35:33

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 2010-03-05 19:41:34

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 2010-03-05 20:17:55

I think using Dispose is preferred because most developers will recognize what to do with it (assuming you're implementing IDispose)

Frank Schwieterman 2010-03-06 02:55:17

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 2010-03-06 14:37:06

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 2010-03-05 19:45:44

@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 2010-03-05 19:57:16

Wow! That is exactly what I would like. Thanks!

hongliang 2010-03-05 20:08:36

ansaurus

tags:

views:

answers:

How should comments for interface and class methods be different

related questions