Repetitive XML comments -- what's the point?

[Dave Sexton]

Hi Noah,

Amen. If you had time to write comments then you had time to write code that didn't need a comment.

So does that mean it's possible to always write code that doesn't require in-line comments either?

 

[Willem van Rumpt]

Amen. If you had time to write comments then you had time to write code
that didn't need a comment.

So your code is commentless?

 

[Bruce Wood]

I've some time ago some transcript of a whiteboard session with Anders
Hejlsberg (I hope everybody know who he is; for the ones that don't this is
the *father* of C#) regarding this issue. It is indeed not very nice that we
need to write the same comments over and over again. As an example when I
override a method I need to copy the comments from the base implementation
and some times I don't have to change anything just because I don't change
the semantic of the method. There are also cases that I need to elaborate
only on the summary or remarks section, but I shouldn't have to write all
teh information for the parameters. Something there should be smart enough
to pick the parts that I haven't changed from the base implementation. The
same (mybe even better example) is the method overloads where we add only
one parameter to the signature.

Here is excerpt of the transcript

"...
Question:

My problem is I've got these XML doc comments that are duplicated. I just
strip off one. I guess it would be a neat language feature to be able to
somehow indicate this is my primary- my big method, right? With all the
parameters. Then the other ones are just going to borrow that XML doc
comment. When XML doc comma,-

Hejlsberg:

Yes, okay. Now that I think is- that's not a bad idea. That yes, they should
be able to share the documentation. I can sympathize with that.
..."
The whole transcript can be found here
http://msdn.microsoft.com/msdntv/transcripts/20040624csharpahTranscript.aspx

There are two issues here. I think that Anders was addressing only the
first, not the second. I've mentioned both as enhancement requests to
C#, and mentioned them in C# chats, but gotten nowhere. The two issues
are:

Issue #1: Overloads. You have three overloads, one of which takes all
five arguments, the other two provide shorter argument lists with
defaulting. Why can't I write comments only for the one that takes all
five arguments, then put some marker on the other overloads that they
should take the bulk of their documentation from the one that takes
five arguments, together with some quick notes about what the
defaulting behaviour is? This is so common and a waste of time and
space updating comments for all X overloads, particularly for
constructors.

Issue #2: Overrides. I inherit from a class and override some of its
methods, but don't significantly change behaviour. Why can't I inherit
the documentation, too, and change the doc only for the things that
changed? This is a more complicated problem, particularly when combined
with the first issue.

As I said, I've never gotten any satisfaction from pressing either of
these issues with the C# team. I do hope that someday they address one
or both of them, because this doc really _is_ useless: it's copied from
one method to another... copy... paste... copy... paste. Ugh.

 

[Mark Wilden]

If you had time to write comments then you had time to write code that
didn't need a comment.

That's a very neat way of putting it.

///ark

 

[Mark Wilden]

[example]
If you are hired to develop a solution for a business and you realize they
have no documentation of their rules or processes, you spend a lot of time
trying to extract that information from the users and existing
infrastructure, which can be a tedious process that is full of
assumptions. It takes analyses, refinement and reiteration to finally be
able to build up the documentation that acurately describes the business
processes and requirements for the new software.

And then a couple of months go by and the documentation is obsolete. Because
we're not paid to keep it up to date - we're paid to deliver functionality.
Now, if there were professional analysts and technical writers employed by
the company, and their paycheck depended on the accuracy of that
documentation, then it would be useful beyond the needs of that one
solution.

In the software world, I think it's even more important to have
documentation (of the code) regardless of whether it's "library" or
business code, so that developers who are not part of the project during
development, peers, managers who are not familiar with code in general,
and the author themselves can understand what was done at a later time
without having to wade through thousands of lines of code or make
assumptions on its behavior.

I've never worked in such a place. Yet I've worked in places that made
money. How could that be? The answer is that documentation, while desirable,
is less desirable than code.

Now I'm not suggesting that good documentation can completely alleviate
the need to look at the source in all circumstances, but I think that's
what developers/documentors should strive to achieve.

As opposed to providing business value? You can't have everything (where
would you put it?).

If you planned the project, understand its design and the business
requirements that it's addressing then documenting code shouldn't be a
difficult process at all.

Actually, it is, else people would do it.

I think good developers should be able to understand and appropriately
comment on there code. After all, you expect them to write appropriate
in-line comments, right?

No, I don't. At my shop, inline comments are forbidden (with rare
exceptions). Tim Ottinger wrote a good blog entry about "comments as
excuses." Inline comments are a way of making excuses for sloppy / confusing
/ complicated code that should be refactored.

Now, sometimes such code is necessary. In that case, we use a special label
and the comment is signed and dated. It's an admission that the code should
be improved.

IMO, if code contains at least one in-line comment it probably requires
some higher-level documentation to describe its overall behavior. Even if
that behavior is simply, "throws ArgumentNullException".

I don't see the benefit of that, at all.

Well I trust documentation that I write and I expect other developers to
write trustworthy documentation as well.

You "expect" it, but since you agree it doesn't happen, isn't this kinda
wishful thinking?

In my experience, most developers feel just like you do about the subject
and fail to write good documentation or any documentation at all, but that
doesn't make it right

At the end of the day, what's right is what produces business value. I
suspect that most code -should- be heavily commented, but that's because
most code is confusing crap - but that's another issue.

I find that in many cases I struggle to understand code that I had written
previously due to poor or absent documentation. The reason why I don't
document in these cases is because I'm usually developing in a RAD-style
and therefore at the time I tend to value new code and testing over
documentation, just like you.

I'm a strong believer in refactoring. My mornings are usually spent making
the previous afternoon's code better. So I don't usually have trouble
understanding my code. In fact, sometimes I look at ten-year-old code I've
written and mourn that it's so good. It seems that I should have improved
more over that time.

Does this mean that you only support the documentation of .DLLs but not
.EXEs? Are they not both code assemblies that, for all intensive purposes,
do exactly the same thing and require an equal amount of documentation?

Well, you can't really call into .EXEs, right?

 

[Dave Sexton]

Hi Bruce,

Issue #1: Overloads. You have three overloads, one of which takes all
five arguments, the other two provide shorter argument lists with
defaulting. Why can't I write comments only for the one that takes all
five arguments, then put some marker on the other overloads that they
should take the bulk of their documentation from the one that takes
five arguments, together with some quick notes about what the
defaulting behaviour is? This is so common and a waste of time and
space updating comments for all X overloads, particularly for
constructors.

I do this now using the "include" element, which allows me to reference external xml documents. I must say that being able to
define an external document to share common parameter definitions has proved to be quite useful and xpath makes it easy to organize.
However, it would be nice as a language feature but I'm not sure that it's possible.

Issue #2: Overrides. I inherit from a class and override some of its
methods, but don't significantly change behaviour. Why can't I inherit
the documentation, too, and change the doc only for the things that
changed? This is a more complicated problem, particularly when combined
with the first issue.

I completely agree with this one! The C# team should acknowledge this as something that would save time and effort when documenting
code, if in fact it's possible.

As I said, I've never gotten any satisfaction from pressing either of
these issues with the C# team. I do hope that someday they address one
or both of them, because this doc really _is_ useless: it's copied from
one method to another... copy... paste... copy... paste. Ugh.

That's a shame. Well if it's any consolation, you're definitely not the only one that feels that way

 

[Mark Wilden]

Sorry, I've should've been more clear. "Go The Source" only works if you
actually *have* the source, which might not me the case in, for instance,
third party software.

I already addressed this, Willem - I agree that if you don't have the
source, you need documentation. This thread is about the knee-jerk practice
of adorning methods with their own names restated in "documentation."

But even in a team environment: I don't want developers to "Go To The
Source", I want them to read the documentation. If you hire new
programmers, do you want them to dive into the source to find out the
intracies for themselves, or do you want to present them with the
documentation? I prefer the last.

I want new programmers to read the code, because 1) the code is always
right, 2) the documentation is never up-to-date and is often even wrong, and
3) reading code is best way to learn how to program and how the team
programs.

It's a programmers job to document his source properly.

That's begging the question. You can't just make such a statement, since
that's precisely what's under disagreement.

Like I said in my original reply, the documentation doesn't bother me when
reading source. It's "offline" reading what interests me: Even without The
Source, I'm able to find out what the interface has to offer me. Add a
reference, and code away.

If you trust it.

///ark

 

[Mark Wilden]

So your code is commentless?

This is not as heretical as it might sound. Especially among agile
developers, comments in code are often felt to be a sign that the code is
not clear. The blocks are too long, or they do too much, or they don't use
good identifiers, or they're prematurely optimized, etc.

Complicated code needs to be commented. Complicated code should be avoided
wherever possible.

See http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode and
http://c2.com/cgi/wiki?ToNeedComments

///ark

 

[Bruce Wood]

I often see code like this:

/// <summary>
/// Removes a node.
/// </summary>
/// <param name="node">The node to remove.</param>
public void RemoveNode(Node node) {
<...>
}

In my view, there is no benefit in doing this. It brings nothing to the
table, and creates the following issues:

o It get in the way of the code -- it's unnecessary noise.

o When something significant changes, both the code and the comment
need to be updated, rather than just the code.

o It often breeds bad code ("don't worry about giving that method a
better name -- the comment explains it well").

I've seen some pretty knowledgeable people write code like this, mind you.
Why do people do it? Is it just a consistency thing? Must every single
method be commented?

There have been oodles of other reactions to this, so I'll try not to
duplicate what has been said. I have two points to make, which I hope
are new(ish).

First, comments are supposed to add an essential element to the code:
the code tells you what the programmer *did*. Comments tell you what
the programmer *meant to do*. Arguably, this latter function is also
served by unit tests, but the documentation *should be* a quick summary
of precisely what the method was meant to do. If it's blindingly
obvious, then that's great, but at least the developer wrote the doc so
you know that he, too, agreed that this method is as simple as it looks
at first glance.

In other words, code without documentation is missing one critical
piece of information: is what the code is currently doing what the
programmer intended it do? Or is it a mistake?

Those here who say that they don't trust documentation and read the
code instead, I'm sorry: I don't believe you. I don't trust
documentation, either. However, what I mean by that is that I read the
documentation, and then evaluate whether it: a) looks complete and
detailed, and b) given what I'm after (which is usually tracking down a
bug) does it seem that the documentation is accurate? If the
documentation seems reasonably clear and it seems unlikely that the
method in question could be the source of the problem, I move on. I
can't imagine that programmers who "don't trust documentation" read
every line of every method they come across while looking for a bug.
I'm guessing that, like me, they read the doc, but warily,
half-expecting it to be inaccurate. It's a guide, not the gospel truth.

That said, when I find a method for which the doc isn't complete, or
which doesn't clearly state what the method really does, I *update the
doc*. No matter who wrote it (and often it was me who wrote it). I see
it as my job to maintain the documentation (the statement of what
*should* be happening in the code) as it is my job to maintain the code
(which makes things happen). If methods have bad doc, I improve the
doc, just as if methods have missing unit tests, I add them. I do that
because I eventually want the comments to do a good job of expressing
the intent of the method, so that later they'll help me decide how to
fix bugs.

Second, there are always those routines that are so obvious and so
simple that they really don't require header comments, so why write the
comments? I will offer another reason beyond those already given by
other posters: discipline. Simply put, people (and thus programmers)
tend to settle into the lowest common denominator of sloth. Yes, it's
probably true that very simple methods don't need even the minimal
documentation that the triple-slash template asks for. However, if you
say to your team that they don't need to document trivial methods, then
shortly thereafter the bar on what constitutes "trivial" will be
lowered to include methods that are a little more complex, but which
one can still guess at what they do without any help. Then the bar will
be lowered further, then further.... The point is that people being as
they are, it's often a good idea to say, "You have to document every
single method" rather than make exceptions and watch the slow slide
into "no documentation".

 

[Dave Sexton]

Hi Mark,

You make some good points. But I disagree with most of them anyway

In the world of RAD documentation is a hassle, it constantly changes when users call up and say, "can you change this behavior?" and
therefore just adds more to the list of things to be maintained during development. However, it is in RAD development that I
believe documentation is the most useful. Xml documentation and in-line commenting. The worst thing as a developer, IMO, is being
assigned to the maintenance, upgrading or current development of a project being RAD-developed without any documentation.
Unfortunately, RAD projects have limited, poor or more commonly, no code documentation what-so-ever. =Nightmare.

In the world of well thought-out, planned and documented solutions, documenting code is quite simple. It can be done after each
segment of code is believed to be finalized and with any luck won't change again. If it does change, in most cases you won't be
wasting too much time simply changing some of the comments but I prefer to leave documentation off until the very "end". I will add
a summary if it would be helpful to developers on the team that might need to reference my code. I'll also make note of any
behavior that is otherwise undocumented in the technical specs and needs to be addressed by the team. As you code the
implementation, it's nice to add in-line comments to relate the line of code back to a business rule that it enforces or to define
the control of flow that might not be obvious when dealing with some of the more robust design patterns, for example. Another
example where I find in-line commenting to be useful is in recursive methods, which are by nature confusing. I don't feel in any
way that my use of in-line commenting proves that I have written bad code. For some developers, that might be true. I don't doubt
it.

I'm not sure which world your organization belongs to, and I acknowledge it could be both or some level of gradient, but I prefer to
stay far away from RAD myself whenever possible. The project I'm working on now is 100% RAD , but fortunately for me I'm the only
developer (well, fortunately and unfortunately ) so I plan to document the large majority of code that is missing
documentation after delivery of the first release. It should be quite easy.

In any case, I don't feel like documenting code is such the chore that you are making it out to be. I think most developers don't
add comments solely because of laziness and look at other excuses for support. Some, unfortunately, can't document their own code
because they really don't understand it. Some, just don't have the skills necessary to adequately document their code. Some, don't
even code properly. These aren't valid excuses to disbelieve in documentation, IMO, but they are valid excuses to take some classes


--
Dave Sexton

[example]
If you are hired to develop a solution for a business and you realize they have no documentation of their rules or processes, you
spend a lot of time trying to extract that information from the users and existing infrastructure, which can be a tedious process
that is full of assumptions. It takes analyses, refinement and reiteration to finally be able to build up the documentation that
acurately describes the business processes and requirements for the new software.

And then a couple of months go by and the documentation is obsolete. Because we're not paid to keep it up to date - we're paid to
deliver functionality. Now, if there were professional analysts and technical writers employed by the company, and their paycheck
depended on the accuracy of that documentation, then it would be useful beyond the needs of that one solution.

In the software world, I think it's even more important to have documentation (of the code) regardless of whether it's "library"
or business code, so that developers who are not part of the project during development, peers, managers who are not familiar
with code in general, and the author themselves can understand what was done at a later time without having to wade through
thousands of lines of code or make assumptions on its behavior.

I've never worked in such a place. Yet I've worked in places that made money. How could that be? The answer is that documentation,
while desirable, is less desirable than code.

Now I'm not suggesting that good documentation can completely alleviate the need to look at the source in all circumstances, but
I think that's what developers/documentors should strive to achieve.

As opposed to providing business value? You can't have everything (where would you put it?).

If you planned the project, understand its design and the business requirements that it's addressing then documenting code
shouldn't be a difficult process at all.

Actually, it is, else people would do it.

I think good developers should be able to understand and appropriately comment on there code. After all, you expect them to
write appropriate in-line comments, right?

No, I don't. At my shop, inline comments are forbidden (with rare exceptions). Tim Ottinger wrote a good blog entry about
"comments as excuses." Inline comments are a way of making excuses for sloppy / confusing / complicated code that should be
refactored.

Now, sometimes such code is necessary. In that case, we use a special label and the comment is signed and dated. It's an admission
that the code should be improved.

IMO, if code contains at least one in-line comment it probably requires some higher-level documentation to describe its overall
behavior. Even if that behavior is simply, "throws ArgumentNullException".

I don't see the benefit of that, at all.

Well I trust documentation that I write and I expect other developers to write trustworthy documentation as well.

You "expect" it, but since you agree it doesn't happen, isn't this kinda wishful thinking?

In my experience, most developers feel just like you do about the subject and fail to write good documentation or any
documentation at all, but that doesn't make it right

At the end of the day, what's right is what produces business value. I suspect that most code -should- be heavily commented, but
that's because most code is confusing crap - but that's another issue.

I find that in many cases I struggle to understand code that I had written previously due to poor or absent documentation. The
reason why I don't document in these cases is because I'm usually developing in a RAD-style and therefore at the time I tend to
value new code and testing over documentation, just like you.

I'm a strong believer in refactoring. My mornings are usually spent making the previous afternoon's code better. So I don't
usually have trouble understanding my code. In fact, sometimes I look at ten-year-old code I've written and mourn that it's so
good. It seems that I should have improved more over that time.

Does this mean that you only support the documentation of .DLLs but not .EXEs? Are they not both code assemblies that, for all
intensive purposes, do exactly the same thing and require an equal amount of documentation?

Well, you can't really call into .EXEs, right?

 

[Mark Wilden]

First, comments are supposed to add an essential element to the code:
the code tells you what the programmer *did*. Comments tell you what
the programmer *meant to do*. Arguably, this latter function is also
served by unit tests

Actually, unit tests tell you both, which is why they're vastly superior to
comments.

As for what someone "intended" to do, there is a school of thought that says
"who cares?"

I think that the actual use is probably a darned sight more important than
the intended use. If things were intended one way, but are generally used
the other way, then the author can either give in to the inevitable and
adjust his intention or else can crusade against the variation in the
actual. Something has to change, and so indeed the code is unfinished. --
TimOttinger

///ark

 

[Mark Wilden]

I'm not sure which world your organization belongs to

We do "medication therapy managment" which helps pharmacists help their
patients with medication interactions.

We're an agile shop. I think that's sort of the successor to RAD.

///ark

 

[Dave Sexton]

Hi Mark,

As for what someone "intended" to do, there is a school of thought that says "who cares?"

I think that the actual use is probably a darned sight more important than the intended use. If things were intended one way, but
are generally used the other way, then the author can either give in to the inevitable and adjust his intention or else can
crusade against the variation in the actual. Something has to change, and so indeed the code is unfinished. -- TimOttinger

Sure, if the author picks up on that. I would expect any developer to make sure their comments are accurately synchronized with
their code. The reader, however, might be inclined to pick up on those mistakes. As Bruce said, he'll go in and change the
comments if he has to. These problems, where the intention differs from the actual are usually referred to as "bugs". The
intention allows the reader to follow along and fix it. The reader, as Bruce also pointed out, is commonly the author. I sometimes
ask when reading old code of mine, "What the hell was I thinking?". It's nice to actually know sometimes

 

[Dave Sexton]

Hi Mark,

Yea - we're probably not going to agree on a lot of things in that case.

Whichever works best for each of us, individually, should be considered the "correct" approach I say. So we're both right as I see
it

 

[Mark Wilden]

These problems, where the intention differs from the actual are usually
referred to as "bugs"

Perhaps, but the actual could be the correct behavior and the intention
could be incorrect. What defines a "bug" is the degree to which a program
delivers a result that its users don't want. At the end of the day, it is
this that must be judged, not intentions (with which the road to hell is
paved with good ones).

///ark

 

[Bruce Wood]

Perhaps, but the actual could be the correct behavior and the intention
could be incorrect. What defines a "bug" is the degree to which a program
delivers a result that its users don't want. At the end of the day, it is
this that must be judged, not intentions (with which the road to hell is
paved with good ones).

I was going to say that you missed my point, but you're closing in on
it....

What comments give you (and I admit that unit tests provide a far more
accurate, if verbose and difficult-to-assimilate version) is what the
author believed should be happening. If the comments disagree with the
actual (as you termed it) -- and here's the key -- *one of them* must
be wrong. Either the comments are wrong or the code is wrong.

It's not that the comments tell you how things should be, rather that a
*disconnect* between the comments and the code tell you that something
is amiss.

Of course, if the comments and the code are in accord, there could
still be a bug, but then it's a higher-level conceptual bug, not a
coding bug.

I *do* care what the original programmer believed should be going on,
because when I'm repairing defects I want to get my head around his/her
original design. Usually there are three or four ways to fix a bug,
only one of which aligns nicely with the original thinking behind the
code. I don't want to waste my time fixing method A, only to find that
that means I have to fix method B, then method C, then method D, then
finally in method E I discover that the original design was to handle
the problem in there, and that was what was broken, not method A.
Nothing wrong with my fix, in a theoretical sense, other than that it
went against the grain of the original design.

True, in an ideal world I could just skim the code and divine the
original design from that, and many times I can, but not always. It's
nice to have some documentation to fall back on.

Of course, as you said, unit tests provide a definitive statement of
whether the parts of the system work as intended, but it's much harder
to wade through hundreds of unit tests to ask the question, "Did the
original author intend that this method explode when passed a null...
did he intend to handle that case somewhere else... of did he miss the
case entirely?"

 

[Mark Wilden]

I *do* care what the original programmer believed should be going on,
because when I'm repairing defects I want to get my head around his/her
original design.

Bah. All I care about is what the code does in the here and now.

True, in an ideal world I could just skim the code and divine the
original design from that, and many times I can, but not always. It's
nice to have some documentation to fall back on.

But the whole problem is when the documentation lies.

Of course, as you said, unit tests provide a definitive statement of
whether the parts of the system work as intended, but it's much harder
to wade through hundreds of unit tests to ask the question, "Did the
original author intend that this method explode when passed a null...
did he intend to handle that case somewhere else... of did he miss the
case entirely?"

Yes, that's certainly true. In general, I would not read the unit tests to
learn how the code works.

I would read the code.

///ark

 

[Dave Sexton]

Hi,

But the whole problem is when the documentation lies.

Bad experiences with documentation doesn't prove anything and is no excuse to support undocumented coding practices. If you
document your code well, I feel it can be quite useful in many aspects of developement. If it's acceptible for the developers in
your organization to write bad documentation then I competely agree with you that you're wasting your time, but that doesn't mean
that good documentation isn't useful and that the only way to get real answers is by looking at the code. Just like you might find
MSDN useful, I like to have a reference on my code just the same. If there are bugs in MSDN's documentation (oh, there are!) that
doesn't simply invalidate the rest and I don't see why it should be any different for custom code.

Yes, that's certainly true. In general, I would not read the unit tests to learn how the code works.

I would read the code.

I don't see how unit testing has anything to do with this. If the unit tests all passed then they probably won't help in
determining the bug. Specifically, because they themselves probably lack documentation and were designed to test the passing
behavior, not the "correct" behavior. If they didn't pass then the code should be fixed before the comments are written anyway,
IMO. In the latter case even, knowing the author's intention might be helpful still to determine the cause of the bug. In any
case, I hope we all agree that unit tests aren't going to help us fix someone else's bugs in most cases but instead to discover and
fix our own early on (with the exception of peer-review, naturally).

If the documentation is incorrect, that too is a bug. Human error is the invariability that makes the entire process suffer. Peer
review is useful to resolve human error and to catch inconsistencies between code and comments as early on as possible, but that too
is susceptible to the inevitability of human error. Occasional human error, however, surely doesn't invalidate the entire purpose
of documentation.

Knowing the author's intent, I believe, allows for the reader to understand the code before they begin to trace the bug to its
origin, hopefully simplifying the entire process. If the author's intent is inconsistent with the code's runtime behavior, then at
least knowledge of the author's intent provides a basis for understanding the code from the perspective of the author, making it
easier to identify type-o's, for example, and other forms of accidental error.

Great discussion everyone. I'm second guessing myself left and right I believe it's reinforcing that my practices are probably
the most suitable choice of those available to meet my needs as a developer. Thanks!

 

[Willem van Rumpt]

I want new programmers to read the code, because 1) the code is always
right, 2) the documentation is never up-to-date and is often even wrong, and
3) reading code is best way to learn how to program and how the team
programs.

Agreed, up to a point. After rereading, my statement came over a bit to
rigid to my own taste. But I prefer to start with the documentation, and
then go the source if necessary.

That's begging the question. You can't just make such a statement, since
that's precisely what's under disagreement.

If not the programmer, then who? Not at all?
I think we'll have to agree to disagree on that one.

If you trust it.

Let's just say I start out with a healthy amount of trust, but adjust my
trust levels depending on the quality of the documentation

 

[Noah Sham]

Given the rarity of comments that I write in code, yes, effectively my code
is commentless.

The only time that I find comments in code useful is when I have to refactor
the 100 line procedure that is bug-laden, brittle and written by another
engineer.