Repetitive XML comments -- what's the point?

**Noah Sham** · Oct 9 '06, 03:15 PM

Re: Repetitive XML comments -- what's the point?

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.

"Willem van Rumpt" <someplace@some wherewrote in message
news:e4gAwih6GH A.3836@TK2MSFTN GP02.phx.gbl...

>>

>>>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.
>>

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

**Ben Newsam** · Oct 9 '06, 03:45 PM

Re: Repetitive XML comments -- what's the point?

On Mon, 9 Oct 2006 11:06:53 -0400, "Noah Sham" <noahsham@veriz on.net>
wrote:

>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.

--
Posted via a free Usenet account from http://www.teranews.com

**Mark Wilden** · Oct 9 '06, 05:35 PM

Re: Repetitive XML comments -- what's the point?

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:e2UvHLc6GH A.4116@TK2MSFTN GP03.phx.gbl...

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** · Oct 9 '06, 05:35 PM

Re: Repetitive XML comments -- what's the point?

"Ben Newsam" <ben.newsam@uko nline.co.ukwrot e in message
news:mhski2dj0u 9rl7q2p1mjmi5h8 rusccunmr@4ax.c om...

>
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 "intentiona l 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** · Oct 9 '06, 05:45 PM

Re: Repetitive XML comments -- what's the point?

"Willem van Rumpt" <someplace@some wherewrote in message
news:e4gAwih6GH A.3836@TK2MSFTN GP02.phx.gbl...

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.

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

>>

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** · Oct 9 '06, 05:55 PM

Re: Repetitive XML comments -- what's the point?

Mark Wilden wrote:

"Bruce Wood" <brucewood@cana da.comwrote in message
news:1160181079 .169707.123560@ m7g2000cwm.goog legroups.com...

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.

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** · Oct 9 '06, 06:55 PM

Re: Repetitive XML comments -- what's the point?

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

"Ben Newsam" <ben.newsam@uko nline.co.ukwrot e in message
news:mhski2dj0u 9rl7q2p1mjmi5h8 rusccunmr@4ax.c om...

On Mon, 9 Oct 2006 11:06:53 -0400, "Noah Sham" <noahsham@veriz on.net>
wrote:
>

>>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.
>
--
Posted via a free Usenet account from http://www.teranews.com
>

**Jon Skeet [C# MVP]** · Oct 9 '06, 07:05 PM

Re: Repetitive XML comments -- what's the point?

Noah Sham <noahsham@veriz on.netwrote:

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.

--
Jon Skeet - <skeet@pobox.co m>
http://www.pobox.com/~skeet Blog: http://www.msmvps.com/jon.skeet
If replying to the group, please do not mail me too

**Mark Wilden** · Oct 9 '06, 07:25 PM

Re: Repetitive XML comments -- what's the point?

"Bruce Wood" <brucewood@cana da.comwrote in message
news:1160417359 .281895.242280@ m7g2000cwm.goog legroups.com...

>
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** · Oct 9 '06, 07:25 PM

Re: Repetitive XML comments -- what's the point?

"Noah Sham" <noahsham@veriz on.netwrote in message
news:u2Pqca96GH A.4116@TK2MSFTN GP03.phx.gbl...

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** · Oct 9 '06, 07:35 PM

Re: Repetitive XML comments -- what's the point?

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 :')

"Mark Wilden" <mwilden@commun itymtm.comwrote in message
news:O7CUFs86GH A.4232@TK2MSFTN GP02.phx.gbl...

"Ben Newsam" <ben.newsam@uko nline.co.ukwrot e in message
news:mhski2dj0u 9rl7q2p1mjmi5h8 rusccunmr@4ax.c om...

>>
>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 "intentiona l 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
>

**Laurent Bugnion** · Oct 9 '06, 08:05 PM

Re: Repetitive XML comments -- what's the point?

Hi,

Noah Sham wrote:

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
--
Laurent Bugnion, GalaSoft
Software engineering: http://www.galasoft-LB.ch
PhotoAlbum: http://www.galasoft-LB.ch/pictures
Support children in Calcutta: http://www.calcutta-espoir.ch

**Mark Wilden** · Oct 9 '06, 08:45 PM

Re: Repetitive XML comments -- what's the point?

"Laurent Bugnion" <galasoft-lb@bluewin.chwr ote in message
news:O286X$96GH A.4176@TK2MSFTN GP02.phx.gbl...

>
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

**Noah Sham** · Oct 9 '06, 08:55 PM

Re: Repetitive XML comments -- what's the point?

Your assumptions about my experience would be wrong.

"Laurent Bugnion" <galasoft-lb@bluewin.chwr ote in message
news:O286X$96GH A.4176@TK2MSFTN GP02.phx.gbl...

Hi,
>
Noah Sham wrote:

>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
--
Laurent Bugnion, GalaSoft
Software engineering: http://www.galasoft-LB.ch
PhotoAlbum: http://www.galasoft-LB.ch/pictures
Support children in Calcutta: http://www.calcutta-espoir.ch

**Willem van Rumpt** · Oct 9 '06, 08:55 PM

Re: Repetitive XML comments -- what's the point?

Mark Wilden wrote:

>
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