Repetitive XML comments -- what's the point?

[Willem van Rumpt]

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

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

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.

--
Willem van Rumpt

[Mark Wilden]

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

"Willem van Rumpt" <someplace@some wherewrote in message
news:eAdpxa%236 GHA.1248@TK2MSF TNGP03.phx.gbl. ..

>
An example is NHibernate

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

I simply want library documentation.

See above.

///ark

[Ben Newsam]

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

On Mon, 9 Oct 2006 10:49:46 -0700, "Mark Wilden"
<mwilden@commun itymtm.comwrote :

>"Ben Newsam" <ben.newsam@uko nline.co.ukwrot e in message
>news:mhski2dj0 u9rl7q2p1mjmi5h 8rusccunmr@4ax. com...

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

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_Contro l, 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.

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

[Ben Newsam]

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

On Mon, 09 Oct 2006 23:11:24 +0200, Willem van Rumpt
<someplace@some wherewrote:

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

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

[Dave Sexton]

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

Hi Mark,

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

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.

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

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.

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

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 ;)

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

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

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

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

--
Dave Sexton

[Dave Sexton]

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

Hi Mark,

No need to throw us a bone -- we're doing just fine ;)

--
Dave Sexton

"Mark Wilden" <mwilden@commun itymtm.comwrote in message news:%238Pp$q96 GHA.4996@TK2MSF TNGP04.phx.gbl. ..

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

[Willem van Rumpt]

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

Ben Newsam wrote:

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

If the algorithm is complex enough: Sure. There are cases when I feel,
though not often, that refactoring an algorithm makes an algorithm
harder to grasp than when it would've been coded as a single method.

From my experience, the quality of comments inside method bodies tend
to go downhill to the level of "declare i and initialize to zero", "loop
through the array and process every element", instead of actual usefull
information. That sort of information clutters the code, and I don't
want it: The code itself explains that.

When I feel the need arise to document the source itself, my first
reaction is to see if the code itself can't be made more self
explanatory. In most cases, it can.

--
Willem van Rumpt

[Laurent Bugnion]

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

Hi,

Mark Wilden wrote:

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

Rereading my reply, I see that it sounds as a criticism, which was not
what I wanted. Sorry about that. I also saw in another post that you use
agile processes. I don't have much experience with that. I guess that
this would explain the "disagreeme nt".

>
How could this be?
>
1) We write good code (that's what I've been saying throughout this thread).

I deliver good code, on time, and it's documented ;-) Granted, I work in
a very traditional firm, where agile development is not widespread. That
said, I like to have the time to document my code. I find that it helps
me to improve it. It's the same train of thoughts that leads me to blog
about my code when I find it interesting enough, I just happen to like
re-analyzing what I did, and understanding it better.

That said, many developers are utterly unable to write good comments, I
will agree to that!

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

That's an interesting way. Thanks for sharing.

Greetings,
Laurent
--
Laurent Bugnion, GalaSoft
Software engineering: http://www.galasoft-LB.ch
Private/Malaysia: http://mypage.bluewin.ch/lbugnion
Support children in Calcutta: http://www.calcutta-espoir.ch

[Laurent Bugnion]

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

Hi,

Rereading my reply, I see that it sounds as a criticism, which was not
what I wanted. Sorry about that.

Greetings,
Laurent

Noah Sham wrote:

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
>>requirement s. 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
Private/Malaysia: http://mypage.bluewin.ch/lbugnion
Support children in Calcutta: http://www.calcutta-espoir.ch

[Ben Newsam]

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

On Tue, 10 Oct 2006 10:18:39 +0200, Willem van Rumpt
<someplace@some wherewrote:

>When I feel the need arise to document the source itself, my first
>reaction is to see if the code itself can't be made more self
>explanatory. In most cases, it can.

People who write the code should not be the ones who decide whether or
not it is self-explanatory. If someone asks "What does this bit do?",
that's the time to add comments. If it does what it is meant to, there
is no need at that stage to change the code itself.

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

[Mark Wilden]

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

"Ben Newsam" <ben.newsam@uko nline.co.ukwrot e in message
news:6dqli2hq48 35r4icu52dneuam sprauc6us@4ax.c om...

>
// 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 );

I think I would refactor that code. Note that you're using rcRect.left - 1
twice and rcRect.top - 1 twice. If you chose to make it three pixels away,
you'd have to change the code in a number of places. I'm not sure
exactly -how- I'd refactor it without knowing the greater context, but
duplication is always a "smell," the removal of which can often make code
more readable.

I am certainly not going to make any of the variables more meaningful than
they already are.

One thing I find detracts from its readability is the hungarian notation.
There's extra characters there with no extra meaning.

If this were C++, I would use the RAII idiom to compress the four lines
dealing with pens.

However, I do grant you that graphical manipulation (which I'm not an expert
on by any means) does lead to more complicated code. And complicated code
should indeed be commented.

///ark

[Mark Wilden]

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

"Ben Newsam" <ben.newsam@uko nline.co.ukwrot e in message
news:nsqli21ntp 5e9m0v2gk40m3up h04mvdrf8@4ax.c om...

>
Not commenting code is a very good way of keeping "ownership" of code.

See my other comment about how, at my shop, we forbid both commenting and
ownership. Turns out the practices work well together.

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.

How could it be useless, when the code itself can be read? Was it really
written that badly?

///ark

[Mark Wilden]

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

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:OqVGhcC7GH A.1012@TK2MSFTN GP05.phx.gbl...

Yes, it most certainly does. But "taking into consideration" doesn't mean
that it's ok to support the development of code without documentation.

If "ok" means, "possible to ship quality product on schedule," then, yes, it
does (at least, at my shop).

It is a skill just like coding is a skill.

Of course you're right. The question is whether developers should spend
their finite time documenting or programming.

They specify what's assumed to be correct at the time they pass.

Sure, just as the documentation (in theory) specifies what's correct at the
time it's written. The big difference is that the tests -prove- something.

The code is never guaranteed to be right, however.

It is guaranteed to be what you ship. It is guaranteed to be what your
customers pay for. It is guaranteed to be what your developers produce. None
of which can by claimed by documentation.

Do you trust the people on your team to write good code?

No. "Trust" has no place in technology. That's why we do frequent
pair-programming and write lots of tests. From what I've seen, the people on
my team -do- write good code and that's my working hypothesis, but I don't
"trust" that they do.

You're really fixated on the idea that you can't trust documentation.

Well, you've admitted yourself that documentation can't be trusted. You go
on to say that we should try to make it more trustworthy, but no one here is
saying that the current state of play is that documentation is worth
trusting.

But then again, agile guys don't write buggy code I guess ;)

We release less buggy code, because we unit-test everything we write.

I'm not sure we're ever going to agree on this. :)

That's not the goal. :)

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

No, we're expressing our ideas. Jump off anytime you want. :)

[Mark Wilden]

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

"Laurent Bugnion" <galasoft-lb@bluewin.chwr ote in message
news:O1z01cE7GH A.2248@TK2MSFTN GP04.phx.gbl...

I like to have the time to document my code. I find that it helps me to
improve it. It's the same train of thoughts that leads me to blog about my
code when I find it interesting enough, I just happen to like re-analyzing
what I did, and understanding it better.

That's sounds similar to what I and others do with "refactorin g," where we
don't just bang out code and move on, but try to think about it and improve
it after the fact.

And I do agree that writing about code (i.e. documenting it) can lead to
insights. This is similar to coding about code, which is what TDD and
unit-testing is about.

///ark

[Noah Sham]

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

1 and 3 also smell like magic numbers that should be named constant. Also,
where are the two pixels referenced in the comment ? :')

"Mark Wilden" <mwilden@commun itymtm.comwrote in message
news:%23X5S%23x I7GHA.1496@TK2M SFTNGP05.phx.gb l...

"Ben Newsam" <ben.newsam@uko nline.co.ukwrot e in message
news:6dqli2hq48 35r4icu52dneuam sprauc6us@4ax.c om...

>>
>// 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 );

>
I think I would refactor that code. Note that you're using rcRect.left - 1
twice and rcRect.top - 1 twice. If you chose to make it three pixels away,
you'd have to change the code in a number of places. I'm not sure
exactly -how- I'd refactor it without knowing the greater context, but
duplication is always a "smell," the removal of which can often make code
more readable.
>

>I am certainly not going to make any of the variables more meaningful
>than they already are.

>
One thing I find detracts from its readability is the hungarian notation.
There's extra characters there with no extra meaning.
>
If this were C++, I would use the RAII idiom to compress the four lines
dealing with pens.
>
However, I do grant you that graphical manipulation (which I'm not an
expert on by any means) does lead to more complicated code. And
complicated code should indeed be commented.
>
///ark
>