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


Mark Wilden wrote:
"Dave Sexton" <dave@jwa[remove.this]online.com> wrote in message
news:OyeO35Z6GHA.1484@xxxxxxxxxxxxxxxxxxxxxxx

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

.

Relevant Pages

  • Re: Off switch blues
    ... it's not a feature it's a bug. ... like, consider a design bug. ... sleep, close the lid, and unplug the keyboard, it's because I intend to ... I don't intend for it to wake back up until I open the ...
    (comp.sys.mac.system)
  • [Full-Disclosure] Shiver me timbers.
    ... my point of view, I'm not intending to tell anybody, ... A security vulnerability is a specific type of bug with specific types ... The only difference I see in the security sector is that there is the _intention_ ...
    (Full-Disclosure)
  • Re: Off switch blues
    ... it's not a feature it's a bug. ... how well-founded the user's expectations were in the first place. ... I don't intend for it to wake back up until I open the ... It doesn't wake up if I unplug it in the first few seconds (while ...
    (comp.sys.mac.system)
  • Re: TDD: Test-Driven Design or Test-Driven Development?
    ... >> software with intention to make it fail you'll succeed again. ... > 'this code does not yet have that ability' as a kind of bug, ... If they write a test that fails due to missing abilities, ... Demonstrating tests are good at regression testing. ...
    (comp.object)
  • Re: [opensuse] (K)NetworkManager openSUSE 11.1 b2
    ... This is intention! ... Never ever mention the bug ID if you have filed one. ... with setups where static NTP configurations aren't adequate. ... The result might not yet been included with the current beta. ...
    (SuSE)