| From: | Mark A Shieh SHODAN+@***.EDU |
|---|---|
| Subject: | [semi-OT] programming languages' evolution |
| Date: | Mon, 1 Feb 1999 19:33:06 -0500 (EST) |
> Mark A Shieh writes:
> > I feel really silly documenting a variable called
> > "OrderWindow" with the comment, "this is the pointer that stores
the
> > OrderWindow for the UI.", but Javadoc wants you to spend that effort.
>
> The problem isn't generally with variables. It's more commonly with
> functions, and I don't mean their internals...
I agree with you on documentation style, it just seemed like
the selfdocumenting stuff wants you to document the tiniest little
details.
> Good documentation should let you treat a function totally as a black box:
> enter these inputs, you get this output, and these side effects occur. And
> functions do have side effects...
Yeah, they've been drilling this into me for ages. I've never
claimed that you shouldn't have this type of documentation, only the
format that the documentation needs to take. My main point is that
that a programmer who produces poorly documented code isn't going to
start producing good code just because he's coding in a language and
environment that produces self-documenting code. As a result, I don't
see that a language with built-in selfdocumenting tools like Java and
Javadoc provides any intrinsic advantages over a language that does
not have these tools (built in).
> When you write the function spec, you'll typically be writing the technical
> documentation, and then you'll write the code. If you have to change the
> code, you could very well change what the function actually does, so you
> have to update the documentation. This is easier if the documentation is in
> the code already.
Ah. I think I glossed over this issue, because I think of the
function spec the way you think of documentation. I'm used to my
documentation appearing next to the function already. I can see where
you're coming from, but it seems to me that you have to be working on
a very large project in order for this to be a problem (not being able
to skim for comments already embedded within the code).
> The other point about documentation is that it should say why you're doing
> it. Sure, I can read a program and say: Yep, you're walking through this
> array, setting data values. But why are you doing it? Legible code (which is
> what is meant by self-documenting code) doesn't describe this.
Sure, definitely. However, this is more of an issue of what
makes up good documentation, not the issue of whether self-documenting
code makes a big difference. I expect a discussion of what good
documentation should consist of to be pretty short and dull, as all
sides are likely to agree on the matter.
> If you don't have documentation, I can assure you that you are not writing
> complex programs, which have to be written by multiple people, and
> maintained by different multiple people who don't have your level of
> programming skill anyway...
Actually, this isn't true. This is what happens at work, and
it's hell. :) Documentation has been working its way into the code
written by some of the people trained to do so, but there's so much
legacy code... Now, if you were to claim that we would be able to
write at least an order of magnitude more effectively if the original
programmers had started with good documentation, I won't disagree. :)
Mark
