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

Tech-Archive recommends: Repair Windows Errors & Optimize Windows Performance

"Dave Sexton" <dave@jwa[remove.this]online.com> wrote in message
news:ubNMQlY6GHA.1188@xxxxxxxxxxxxxxxxxxxxxxx

[example]
If you are hired to develop a solution for a business and you realize they
have no documentation of their rules or processes, you spend a lot of time
trying to extract that information from the users and existing
infrastructure, which can be a tedious process that is full of
assumptions. It takes analyses, refinement and reiteration to finally be
able to build up the documentation that acurately describes the business
processes and requirements for the new software.

And then a couple of months go by and the documentation is obsolete. Because
we're not paid to keep it up to date - we're paid to deliver functionality.
Now, if there were professional analysts and technical writers employed by
the company, and their paycheck depended on the accuracy of that
documentation, then it would be useful beyond the needs of that one
solution.

In the software world, I think it's even more important to have
documentation (of the code) regardless of whether it's "library" or
business code, so that developers who are not part of the project during
development, peers, managers who are not familiar with code in general,
and the author themselves can understand what was done at a later time
without having to wade through thousands of lines of code or make
assumptions on its behavior.

I've never worked in such a place. Yet I've worked in places that made
money. How could that be? The answer is that documentation, while desirable,
is less desirable than code.

Now I'm not suggesting that good documentation can completely alleviate
the need to look at the source in all circumstances, but I think that's
what developers/documentors should strive to achieve.

As opposed to providing business value? You can't have everything (where
would you put it?).

If you planned the project, understand its design and the business
requirements that it's addressing then documenting code shouldn't be a
difficult process at all.

Actually, it is, else people would do it.

I think good developers should be able to understand and appropriately
comment on there code. After all, you expect them to write appropriate
in-line comments, right?

No, I don't. At my shop, inline comments are forbidden (with rare
exceptions). Tim Ottinger wrote a good blog entry about "comments as
excuses." Inline comments are a way of making excuses for sloppy / confusing
/ complicated code that should be refactored.

Now, sometimes such code is necessary. In that case, we use a special label
and the comment is signed and dated. It's an admission that the code should
be improved.

IMO, if code contains at least one in-line comment it probably requires
some higher-level documentation to describe its overall behavior. Even if
that behavior is simply, "throws ArgumentNullException".

I don't see the benefit of that, at all.

Well I trust documentation that I write and I expect other developers to
write trustworthy documentation as well.

You "expect" it, but since you agree it doesn't happen, isn't this kinda
wishful thinking?

In my experience, most developers feel just like you do about the subject
and fail to write good documentation or any documentation at all, but that
doesn't make it right ;)

At the end of the day, what's right is what produces business value. I
suspect that most code -should- be heavily commented, but that's because
most code is confusing crap - but that's another issue.

I find that in many cases I struggle to understand code that I had written
previously due to poor or absent documentation. The reason why I don't
document in these cases is because I'm usually developing in a RAD-style
and therefore at the time I tend to value new code and testing over
documentation, just like you.

I'm a strong believer in refactoring. My mornings are usually spent making
the previous afternoon's code better. So I don't usually have trouble
understanding my code. In fact, sometimes I look at ten-year-old code I've
written and mourn that it's so good. It seems that I should have improved
more over that time. :)

Does this mean that you only support the documentation of .DLLs but not
.EXEs? Are they not both code assemblies that, for all intensive purposes,
do exactly the same thing and require an equal amount of documentation?

Well, you can't really call into .EXEs, right?


.

Relevant Pages

  • Re: Why use the TeX suite?
    ... the importance of documentation --- and it's a bit surprising they ... for that business' documents, ... (just a typo), bad spelling, bad grammar (just a ... The TeX community needs to be concerned about the presentation of mathematics and the use of proper mathematical notation. ...
    (comp.text.tex)
  • Re: Which do you prefer?
    ... or because of a business reason. ... programmers have quit. ... developers recognize it as a "stable sort" just by reading the code? ... An automated system for producing printed documentation ...
    (microsoft.public.dotnet.languages.vb)
  • Re: Food for Thought
    ... > Producing such documentation costs money that few businesses are willing ... Then why do you think business collectively spends millions of dollars each ... contrary to your point of view, that most do think managing risk it is very ... business with that resource. ...
    (comp.security.misc)
  • Re: Food for Thought
    ... > Producing such documentation costs money that few businesses are willing ... Then why do you think business collectively spends millions of dollars each ... contrary to your point of view, that most do think managing risk it is very ... business with that resource. ...
    (comp.os.ms-windows.nt.admin.security)
  • Re: Food for Thought
    ... > Producing such documentation costs money that few businesses are willing ... Then why do you think business collectively spends millions of dollars each ... contrary to your point of view, that most do think managing risk it is very ... business with that resource. ...
    (microsoft.public.win2000.security)