[MUD-Dev] Documentation

[Adam Martin]

----- Original Message -----
From: "Brian Hook" <brianhook at pyrogon.com>
> Robin Lee Powell said:

>> Of course, my memory is absolutely pathetic, so that may have
>> something to do with it.  Also, I've had to take over large
>> pieces of undocumented code from others.  It's a nightmare.

> I don't believe in documentation, and barely even believe in
> comments.  The reason is pretty simple: you can spend as much time
> writing comments/docs as you do code, and inevitably they get out
> of sync.

> Code doesn't lie, comments do. And there is no worse feeling than
> "debugging" something only to find out that it was never broken --
> the comments were just out of date.

> I also believe that if you can't understand what code is doing the
> first time you glance at it, then there are better than even odds
> that the code is written poorly.

> Well written code should read like prose.  It's when it reads like
> code that you have problems.

I'm guessing you've never been fortunate enough to see good
comments; otherwise I find it hard to see how you'd have failed to
notice what a difference it makes to have even just a conceptual
explanation of what the code is about to do in the next 20-50 lines
(or more, depending on how self-evident the names of method-calls
and libraries being used in those lines etc are).

I got badly bruised when my second ever commercial project involved
having to work with code documented in the fashion you describe -
out of date comments which weren't even clear (often didn't even
make logical sense!) in the first place. But giving up at that point
and saying its better not to spend the time writing them seems very
defeatist. As a rough estimate from years in various teams -
testing, development and design - I'd guess that good comments
enable people to really thoroughly understand code about 4 to 10
times faster than without them, or with sparse poor comments, which
are next to useless. c.f. the guidelines Sun issue for using
JavaDoc, with an explicit command along the lines of "DO NOT
paraphrase a piece of code into English, and make that the
comment. Explain, don't relate, what the code is going to do. Anyone
can read the code and see what its doing, so saying that again is
just a waste of everyone's time."

Well written comments ought to provide a high-level of understanding
of what the code is doing, why its doing it that way as opposed to
any other, and where this processing fits in to the bigger picture
of the class/module/library/application as a whole.

I think the situation you're getting at is where the comments are
used to explain what the hell the programmer was on when he was
writing a lump of impenetrable code, and using all sorts of dodgy
tricks that were unnecessary and end up confusing most other
people. Example from one game that some ex-colleagues were working
on, and to explain their depression to me they showed me what they
had to cope with: The previous programmers (who had been fired) had
obviously not liked their jobs much...the variables were named
"var1, var2 ... var20", "I_hate_this_job", "X_Sucks" (X was the name
of the project manager), and a whole load of expletives.

Adam M
_______________________________________________
MUD-Dev mailing list
MUD-Dev at kanga.nu
https://www.kanga.nu/lists/listinfo/mud-dev