Repetitive XML comments -- what's the point?

[tjb]

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?

[Mark Wilden]

"Bruce Wood" <br*******@canada.comwrote in message
news:11**********************@c28g2000cwb.googlegr oups.com...

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

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:el**************@TK2MSFTNGP03.phx.gbl...

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,

<snip>

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

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

--
Dave Sexton

"Mark Wilden" <mw*****@communitymtm.comwrote in message news:%2****************@TK2MSFTNGP05.phx.gbl...

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message news:el**************@TK2MSFTNGP03.phx.gbl...

>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

[Mark Wilden]

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:Oy**************@TK2MSFTNGP05.phx.gbl...

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]

Mark Wilden wrote:

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:Oy**************@TK2MSFTNGP05.phx.gbl...

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

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]

"Bruce Wood" <br*******@canada.comwrote in message
news:11**********************@m7g2000cwm.googlegro ups.com...

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,

<snip>

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

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.

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

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!

--
Dave Sexton

[Willem van Rumpt]

Mark Wilden wrote:

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

>

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

>

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

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 :)
--
Willem van Rumpt

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

"Willem van Rumpt" <someplace@somewherewrote in message
news:eV**************@TK2MSFTNGP04.phx.gbl...

Noah Sham wrote:

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

--
Willem van Rumpt

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

"Willem van Rumpt" <someplace@somewherewrote in message
news:e4**************@TK2MSFTNGP02.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]

On Mon, 9 Oct 2006 11:06:53 -0400, "Noah Sham" <no******@verizon.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]

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:e2**************@TK2MSFTNGP03.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]

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:mh********************************@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.

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]

"Willem van Rumpt" <someplace@somewherewrote in message
news:e4**************@TK2MSFTNGP02.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]

Mark Wilden wrote:

"Bruce Wood" <br*******@canada.comwrote in message
news:11**********************@m7g2000cwm.googlegro ups.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]

And many times you have not revisited your code and the comments you wrote
provided no value.
"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:mh********************************@4ax.com...

On Mon, 9 Oct 2006 11:06:53 -0400, "Noah Sham" <no******@verizon.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]]

Noah Sham <no******@verizon.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 - <sk***@pobox.com>
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]

"Bruce Wood" <br*******@canada.comwrote in message
news:11**********************@m7g2000cwm.googlegro ups.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]

"Noah Sham" <no******@verizon.netwrote in message
news:u2**************@TK2MSFTNGP03.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]

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" <mw*****@communitymtm.comwrote in message
news:O7**************@TK2MSFTNGP02.phx.gbl...

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:mh********************************@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.

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

[Laurent Bugnion]

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]

"Laurent Bugnion" <ga*********@bluewin.chwrote in message
news:O2**************@TK2MSFTNGP02.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]

Your assumptions about my experience would be wrong.

"Laurent Bugnion" <ga*********@bluewin.chwrote in message
news:O2**************@TK2MSFTNGP02.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]

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

[Willem van Rumpt]

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]

"Willem van Rumpt" <someplace@somewherewrote in message
news:eA****************@TK2MSFTNGP03.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]

On Mon, 9 Oct 2006 10:49:46 -0700, "Mark Wilden"
<mw*****@communitymtm.comwrote:

>"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:mh********************************@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_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.

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

[Ben Newsam]

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

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

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]

Hi Mark,

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

--
Dave Sexton

"Mark Wilden" <mw*****@communitymtm.comwrote in message news:%2****************@TK2MSFTNGP04.phx.gbl...

"Noah Sham" <no******@verizon.netwrote in message news:u2**************@TK2MSFTNGP03.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]

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]

Hi,

Mark Wilden wrote:

"Laurent Bugnion" <ga*********@bluewin.chwrote in message
news:O2**************@TK2MSFTNGP02.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 "disagreement".

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

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" <ga*********@bluewin.chwrote in message
news:O2**************@TK2MSFTNGP02.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
Private/Malaysia: http://mypage.bluewin.ch/lbugnion
Support children in Calcutta: http://www.calcutta-espoir.ch

[Ben Newsam]

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

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

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:6d********************************@4ax.com...

>
// 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]

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:ns********************************@4ax.com...

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

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:Oq**************@TK2MSFTNGP05.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]

"Laurent Bugnion" <ga*********@bluewin.chwrote in message
news:O1**************@TK2MSFTNGP04.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 "refactoring," 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]

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" <mw*****@communitymtm.comwrote in message
news:%2******************@TK2MSFTNGP05.phx.gbl...

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:6d********************************@4ax.com...

>>
// 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]

"Noah Sham" <no******@verizon.netwrote in message
news:Oa**************@TK2MSFTNGP04.phx.gbl...

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

I would say that 1 should be a parameter to a function/method and the name
of that function/method would do a lot to obviate the comment. 3 should be
replaced by (sizeof ptPoints / sizeof *ptPoints). As for the two pixels, yer
right - that comment may be correct, but it's a little confusing (maybe the
line is two pixels from the interior of rcRect?).

It takes a brave man to post code here. :)

>"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:6d********************************@4ax.com.. .

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

[Ben Newsam]

On Tue, 10 Oct 2006 09:59:46 -0700, "Mark Wilden"
<mw*****@communitymtm.comwrote:

>"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:ns********************************@4ax.com.. .

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

It wasn't brilliant, no. Pretty hard to read. That's the real world
for you.

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

[Dave Sexton]

Hi Mark,

You've grabbed single lines out of my response and responded to them and it's not the first time. I hope you realize that you've
responded in a partial-context and that you're making it difficult for me to express my ideas to you when you're not addressing all
of them. I keep writing the same things over and over again and because of this and I see that you are doing the same, so I was
hoping that we could come to some agreement and say, for instance, that whatever works for each of us, individually, is the right
choice.

Apparently you'd rather just debate this topic until your head falls off, but we're never going to be finished "expressing our
ideas" unless we start agreeing on some things. And since that's never going to happen without analyzing the root of our debate,
which is our differences in process guidance, then we're going to just keep spinning our wheels. I'm not sure this is the
appropriate thread to do that, however, since it really is only about documentation (at the highest-level), but it's definitely very
important at a minimum to acknowledge that our experience might very well be different and that if we keep discussing this topic
using statements such as, "in my shop", "in my experience", "I've seen", "usually", "sometimes", "often" without definite context
and statistics then our differences in experience are just going to dictate whether we find documentation useful and we're never
going to agree one way or the other.

I think we have both made our points clear and I'm not sure there's anything more to say other than I find custom documentation to
be useful and that you don't, largely due to trust and time issues, and both of us acknowledge some exceptions to these beliefs.

If you're curious as to the root of the choices I make with regards to documentation in my code then you can read about the MSF
(Microsoft Solution Framework), which is a process guidance based largely on scientific principles and consulting experience.
Although the MSF might not directly address the level of xml commenting that I prefer, it's those governing principals that I use
when making the choice to document my code and it's the reason why I hope others do the same if I have to work on their code.

:)

--
Dave Sexton

"Mark Wilden" <mw*****@communitymtm.comwrote in message news:%2****************@TK2MSFTNGP03.phx.gbl...

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message news:Oq**************@TK2MSFTNGP05.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. :)

[Ben Newsam]

On Tue, 10 Oct 2006 09:54:42 -0700, "Mark Wilden"
<mw*****@communitymtm.comwrote:

>"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:6d********************************@4ax.com.. .

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

So would I. Er... probably. Possibly. I wasn't illustrating my point
with a piece of perfect code, but with some *real* code that will
definitely *not* be altered without a really good reason (such as it
not working any more).The point is that the comments make it a whole
lot easier to understand. The code itself simply is what it is, it
does its job (whatever that happens to be) and therefore does not need
to be fiddled with in any way. Whatever circumstances that code was
written in, and whatever language it is written in, are irrelevant.
Yes, it can be improved, but it won't be, and when I found that
snippet I was grateful for the comments included.

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

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

[Bruce Wood]

Ben,

Your posts are appearing as one day into the future, which means that
topics to which you respond are staying at the top of the heap in my
newsreader.

Please fix your system clock....

Ben Newsam wrote:

On Tue, 10 Oct 2006 09:54:42 -0700, "Mark Wilden"
<mw*****@communitymtm.comwrote:

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:6d********************************@4ax.com...

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

So would I. Er... probably. Possibly. I wasn't illustrating my point
with a piece of perfect code, but with some *real* code that will
definitely *not* be altered without a really good reason (such as it
not working any more).The point is that the comments make it a whole
lot easier to understand. The code itself simply is what it is, it
does its job (whatever that happens to be) and therefore does not need
to be fiddled with in any way. Whatever circumstances that code was
written in, and whatever language it is written in, are irrelevant.
Yes, it can be improved, but it won't be, and when I found that
snippet I was grateful for the comments included.

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

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

[Ben Newsam]

On 11 Oct 2006 09:30:41 -0700, "Bruce Wood" <br*******@canada.com>
wrote:

>Ben,

Your posts are appearing as one day into the future, which means that
topics to which you respond are staying at the top of the heap in my
newsreader.

Please fix your system clock....

Oooh yes! Blimey. Thanks.

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

[Mark Wilden]

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:de********************************@4ax.com...

>>I think I would refactor that code.

So would I. Er... probably. Possibly. I wasn't illustrating my point
with a piece of perfect code, but with some *real* code that will
definitely *not* be altered without a really good reason (such as it
not working any more).

One of the tenets of "agile" is that working code should indeed be
refactored to make it more readable and easier to use. In this case, I think
that refactoring would make the code more reusable as well, which would have
payoffs down the road (though agile tends not to value "down the road" very
highly).

One of the points we have been making is that the time taken to write a
comment can be spent making the code itself self-commenting. This has the
benefits mentioned above of well-factored code, plus it avoids the (almost
inevitable) drawbacks of the comments falling out of sync with the code.
Well-factored code is always correct with respect to itself. Comments may or
may not be, and it take additional developer cycles to determine such
correctness. Even if you were to read your comment years later, I think you
would probably still verify that the code still matched the comment,
wouldn't you?

The code itself simply is what it is, it
does its job (whatever that happens to be) and therefore does not need
to be fiddled with in any way.

What we're saying is that if you "fiddle" with the code a bit, you don't
need to comment it. And you end up with better code, to boot. That's sounds
like a win to me.

///ark

[Ben Newsam]

On Wed, 11 Oct 2006 10:04:51 -0700, "Mark Wilden"
<mw*****@communitymtm.comwrote:

>"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:de********************************@4ax.com.. .

>The code itself simply is what it is, it
does its job (whatever that happens to be) and therefore does not need
to be fiddled with in any way.

What we're saying is that if you "fiddle" with the code a bit, you don't
need to comment it. And you end up with better code, to boot. That's sounds
like a win to me.

I have learnt, over many, many years experience, not to "fiddle" with
code at all unless it is necessary. What seems like an improvement can
have all sort of repercussions elsewhere.

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

[Mark Wilden]

"Ben Newsam" <be********@ukonline.co.ukwrote in message
news:b7********************************@4ax.com...

>
I have learnt, over many, many years experience, not to "fiddle" with
code at all unless it is necessary. What seems like an improvement can
have all sort of repercussions elsewhere.

It's true that ruthless refactoring isn't practical without unit tests.

///ark