Repetitive XML comments -- what's the point?

[Noah Sham]

Re: programmers responsibility. My view is that a programmer has only one
responsibility: write bug-free code that meets the software requirements.
Documenting source is last on the list of activities that impact this
responsibility.

 

[Ben Newsam]

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.

I disagree completely. Many times, I have revisited code that I wrote
years before, and have been glad of the notes that I left for myself.

 

[Mark Wilden]

Bad experiences with documentation doesn't prove anything and is no excuse
to support undocumented coding practices.

Coding is a human activity, and the way humans act has to be taken into
consideration.

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.

Actually, in TDD, the unit tests do specify the "correct" behavior, because
they drive the development. You don't write code until you have a failing
test.

In the latter case even, knowing the author's intention might be helpful
still to determine the cause of the bug.

Or it might be utterly misleading. The -only- thing that's guaranteed to be
completely true is the code.

If the documentation is incorrect, that too is a bug.

The question is whether it's better to fix those bugs or fix other bugs
(like the ones the user sees). It's a question of opportunity cost. In an
ideal world, it would be great to have complete, perfect documentation. We
don't live there.

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.

This assumes that the documentation accurately reflects that intent. And
that the intent has any relationship to the current code. Both of which are
highly suspect.

///ark

 

[Mark Wilden]

I disagree completely. Many times, I have revisited code that I wrote
years before, and have been glad of the notes that I left for myself.

I would humbly suggest that, in that case, you should write shorter methods,
with longer identifiers.

There is a style called "intentional programming" which assumes you are
using a super-library with every function you need, and you can do your job
just by calling these functions. Then you write those functions (an earlier
generation called this "functional decomposition"). This style leads to very
readable, understandable code, where comments are redundant.

When I'm tempted to write a comment, instead I try to see how to make the
code readable enough so that it doesn't need a comment.

///ark

 

[Mark Wilden]

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.

1) How do you know if when it's necessary?
2) How do you step through documentation in a debugger?
3) How do you add functionality to documentation?

We produce code, not documentation. Except for highly-maintained library
code, it's -always- necessary to go to the source, in my experience. May as
well cut out the middle man.

If not the programmer, then who? Not at all?

In most cases, "not at all." The code is the best documentation, if it's
written well. The worse it's written, the more it needs documentation.

///ark

 

[Bruce Wood]

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.

But you miss my point entirely. The code can't tell you. It can tell
you only what it *does*, not what it *should do*.

 

[Noah Sham]

And many times you have not revisited your code and the comments you wrote
provided no value.

 

[Jon Skeet [C# MVP]]

And many times you have not revisited your code and the comments you wrote
provided no value.

That's true - but then often I've used finally statements in case an
exception has been thrown in places where in reality no exception has
been thrown.

I agree with only writing comments where they're useful, but they can
sometimes be invaluable.

 

[Mark Wilden]

But you miss my point entirely. The code can't tell you. It can tell
you only what it *does*, not what it *should do*.

Ah, I see what you mean.

In my practice, tests do document what the code "should" do, because they
are written before the code. The tests are the specification.

So the code (in my view) is the perfect documentation for what the code
does, and the unit and acceptance tests are the perfect documentation for
what the code should do.

All that said, there are places for external documentation. However, as an
agilist, I do prefer code to documentation, where there's a choice.

///ark

 

[Mark Wilden]

And many times you have not revisited your code and the comments you wrote
provided no value.

Just to play the opposite side of the fence for a second, writing
comments -might- provide a benefit even if they're not read, in that if you
have trouble writing a comment, you might want to rethink the code itself.
Sort of the same thing as writing a test that never fails - the very act can
point out potential improvements in the target code.

Not that that's a good enough reason for comments, of course.

///ark

 

[Noah Sham]

Well said. I learned how to program using functional decomposition....used
it a few minutes ago...and will use it tomorrow. In fact, I will continue
to use the process with whatever linguistic or syntactic sugar the newer
generation provides :')

 

[Laurent Bugnion]

Hi,

Re: programmers responsibility. My view is that a programmer has only one
responsibility: write bug-free code that meets the software requirements.
Documenting source is last on the list of activities that impact this
responsibility.

I take it that you don't work in a team, and that you were never
confronted with the departure of one colleague, and the need to take
over his code... Comments and documentation are invaluable in this case.

To me, undocumented code is unfinished code.

HTH,
Laurent

 

[Noah Sham]

Your assumptions about my experience would be wrong.

 

[Mark Wilden]

I take it that you don't work in a team, and that you were never
confronted with the departure of one colleague, and the need to take over
his code... Comments and documentation are invaluable in this case.

I work on a team where comments are forbidden (except for exceptional
conditions). And yet we deliver quality software on time.

How could this be?

1) We write good code (that's what I've been saying throughout this thread).

2) We all work on all the code. When it comes time to divide up tasks,
preference is given to working on code you haven't worked on before. We
don't have the concept of "taking over his code." We often work on code
together. We do most design in common.

Works for us!

///ark

 

[Willem van Rumpt]

1) How do you know if when it's necessary?

When the described functionality and actual results start to deviate. An
example is NHibernate. I used the documentation to get me up to speed. I
switched to source mode when one of the more exotic mappings offered
didn't work as described (or as I interpreted, I'm not saying
documentation is always perfect). I can assure you this method will get
you going with NHibernate a *lot* faster than stepping through the code

2) How do you step through documentation in a debugger?
3) How do you add functionality to documentation?

Silly questions.

We produce code, not documentation. Except for highly-maintained library
code, it's -always- necessary to go to the source, in my experience. May as
well cut out the middle man.

Apparently not "we". Me, my teammembers, previous teammembers, at both
my current and previous jobs. It's not that every method has text the
size of War And Peace over it. Clear, concise, and to the point
documentation.

In most cases, "not at all." The code is the best documentation, if it's
written well. The worse it's written, the more it needs documentation.

We're talking about a different form of documentation here, and one we
agree on. I despise what I would call (for lack of a better word)
"inline" documentation. In my opinion, if there needs to be
documentation /inside/ the method body, you better have a damn good
reason, and the method is a prime candidate for refactoring.

I simply want library documentation. Descriptions of the types and the
interfaces they offer, expected results, possible exceptions, those kind
of things. What it does *not* have to document is *how* it does its job.

 

[Willem van Rumpt]

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.

Somewhere along the line, we've gone from documenting methods (XML
comments) to documenting within method bodies.

I don't use (or rarely use) comments *in* code. I document the methods
(the XML comments). It documents what they do, what parameters they
need, exceptions that may be thrown. It does *not* have to document
*how* it does it. In short: I document the interface. That's what's
important for me.

 

[Mark Wilden]

An example is NHibernate

Woah, woah, woah. I have been explicitly excluding library code.

I simply want library documentation.

See above.

///ark

 

[Ben Newsam]

I would humbly suggest that, in that case, you should write shorter methods,
with longer identifiers.

Well... let me see... it's no good me producing any C# examples,
because C# hasn't been going long enough. OK, here is a snippet from a
function, that might or might not still be used for anything, called
Frame_3D_Control, written in C (or is it C++, I forget?). I find it
makes a lot more sense to me (even though I wrote it myself back in
19xx) with the comment than without it.

// Up the left side and across the top,
// two pixels away from the window.
hPen = CreatePen ( PS_SOLID, 0, bRaised ? WHITE : BLACK );
hOldPen = SelectObject ( hDC, hPen );
ptPoints[0].x = rcRect.left - 1;
ptPoints[0].y = rcRect.bottom;
ptPoints[1].x = rcRect.left - 1;
ptPoints[1].y = rcRect.top - 1;
ptPoints[2].x = rcRect.right;
ptPoints[2].y = rcRect.top - 1;
Polyline ( hDC, ptPoints, 3 );
SelectObject( hDC, hOldPen );
DeleteObject( hPen );

Now, with code such as the above, I am certainly not going to make any
of the variables more meaningful than they already are. It is simply
good solid workaday stuff that does its job with no fuss or bother,
and is commented so that the next person (whether it is me or someone
else) can make some sense of it.

 

[Ben Newsam]

I don't use (or rarely use) comments *in* code.

Not commenting code is a very good way of keeping "ownership" of code.
I once worked for a company who thought they had bought the source
code to a large project. Well, they had, I suppose. Unfortunately, one
of the programmers for the selling company thought that the code was
"his", so he removed all the comments, thus rendering it pretty much
useless. I found, as the new maintainer of the code, that it was very
hard to keep the project going, even though about 40% of the code had
actually been written by me several years previously. Good, relevant
comments are invaluable.

 

[Dave Sexton]

Hi Mark,

Coding is a human activity, and the way humans act has to be taken into consideration.

Yes, it most certainly does. But "taking into consideration" doesn't mean that it's ok to support the development of code without
documentation. It just means that you need to take as much care in ensuring that your developers are skilled enough to write
documentation as they are skilled to write code. It's not a valid excuse just because your group of developers doesn't write
documentation that you find to be useful. It is a skill just like coding is a skill.

Actually, in TDD, the unit tests do specify the "correct" behavior, because they drive the development. You don't write code until
you have a failing test.

They specify what's assumed to be correct at the time they pass. Finding out that the code you've written is a bug later on is what
I was referring to. In other words, it's "correct" when you right it but it's intention may turn out to be wrong.

Also, I mentioned "accidental" bugs as opposed to "purposeful" ones (and I don't know of any guidance that makes this distinction
but I'd be happy to learn of two other words that are more descriptive then "accidental" and "purposeful"). The purposeful bugs are
those that you intentionally code, following specifications and addressing requirements, but then they turn out to be wrong or the
overal design was incorrect and didn't actually address the business requirements. Accidental bugs, such as type-o's and logical
error, occur when your code does not faithfully implement your intentions. I believe that documentation can help to fix both cases
of bugs by allowing the reader to follow along with the user's intentions, through there code, without having to infer them from the
code itself, which is obviously wrong - the reason you are fixing a bug. Especially useful for "accidental" bugs, which is why I
mentioned it.

Or it might be utterly misleading. The -only- thing that's guaranteed to be completely true is the code.

The code is never guaranteed to be right, however. But again you shouldn't base your entire opinion on bad experiences (or no
experiences) with documentation and assume that nobody knows how to write it. If you have that skill, it's very useful. Do you
trust the people on your team to write good code? I'd like to trust people as much as I can to write good code and appropriate
documenation, otherwise they might not be at a high enough skill level to be working on the project in the first place. Peer-review
helps to alleviate mistakes that people make, no matter how high their skill level. Documentation is even useful in peer-review,
and can be reviewed itself for accuracy much like code. It's just another aspect of development that has helped me in the past and
so I continue to use it and will continue using it into the future.

You're really fixated on the idea that you can't trust documentation. I feel that more often than that you can't trust certain
developer's code. But then again, agile guys don't write buggy code I guess

The question is whether it's better to fix those bugs or fix other bugs (like the ones the user sees). It's a question of
opportunity cost. In an ideal world, it would be great to have complete, perfect documentation. We don't live there.

I think we've been discussing whether to even write documentation in the first place or not. But if you are writing appropriate
documentation it's much easier than writing code and there is far less often bugs in documentation than code as long as time is
invested to keep it up to date. That's why I document my code (aside from in-line comments) after finalization, whenever possible,
so that code documentation is usually a one-time deal. And if you have planned your design ahead of time then you might just find
your code even easier to comment on. You can also use xml-includes to pull in repetitive comments. I feel that the cost of writing
documentation is low, especially if you can realize its usefulness to help fix bugs, change code or update legacy code at a later
time, of which the cost without documentation is usually quite high.

I think we're going in circles a bit here. We have different methodologies and guidance that we follow as developers and it
dictates how we use documentation in planning and code. I'm not sure we're ever going to agree on this.

This assumes that the documentation accurately reflects that intent. And that the intent has any relationship to the current code.
Both of which are highly suspect.

Again, if a developer writes comments on code and they have no relation, then the developer isn't doing their job. It's just that
simple. If you trust them to write code, and they have that skill, you can trust them to write documentation too if they have that
skill as well. I really think you're having trouble letting go the argument that documentation isn't useful because sometimes it's
just wrong. And I think your exaggerating its negative impact on the development lifecycle too.

Man, I wish we could agree on something! Don't you just feel like we're both just spinning our wheels?

How about we agree at least that we can do whatever works for us and both be "right". If you find that you're productive without
documenting your code, and I find it to be beneficial, then we are both doing the "right" thing. There is definately way too many
variables here to be analyzed, including a lot of things we haven't even touched on. Differences between RAD/Agile/MSF and any
other guidance out there. Actually, there are a lot of different development lifecycle methods because there are a lot of different
needs, so we really can't argue that any one is "truly" better, generally speaking, without context and actual statistics.

Thanks for the discussion so far