[MUD-Dev] Documentation

[Brian Hook]

At 11:29 AM 10/19/01 +0100, Adam Martin wrote:

> 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'm not against reading good comments, I'm against writing bad ones.
And, in my experience, with any iterative development process most
comments are woefully out of date (and thus more dangerous than
useful).  In the situations where the comments are religiously
updated, I find myself spending more time writing comments than
code, only to end up throwing away the comments when the code
changes.  And with an iterative development process, a LOT of code
gets rewritten and thrown away.  In the past week alone I've
rewritten my sound system and entity management system.  It would
have taken several more days just to go through and document it
correctly.

That said, when I know something should be documented (or fixed or
whatever) I place one of the following comments:

  // document(bwh)
  // fixme(bwh) - this may break under some conditions
  // optimize(bwh) - remove linear search, put in hash table
  // do not merge - fatal bug must be fixed before checking in code

Before I commit my source I make sure no "do not merge" comments
exist, for example if I'm commenting stuff out for testing I put in
"do not merge" comments.

When I'm bored and don't feel like writing code then I do a grep for
whatever I feel like updating and go with it.  It allows me to work
on what I'm doing with 100% focus, and I push things onto a "todo
stack" without worrying about the details right then.

Just to be clear, I LIKE comments and clear documentation, but I
think that in most cases people just don't do them right without
sacrificing a huge chunk of development time.  I much prefer to
hammer out the design and impelmentation fairly clearly, THEN write
good comments for yourself and others.

> and saying its better not to spend the time writing them seems
> very defeatist.

No, it's practical =)

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

In my experience, well written code makes a much bigger difference.
That's where I concentrate my efforts.  I use good whitespace habits
and well written variable names.  I generally avoid "int i" and
globals with names like "cItm".  I also don't play the dorky "How
much code can I shove into a single line?" game that many
programmers feel obligated to do:

  dmg( d & 2 ? x  : x * ( wf & 1 ? 1 : 4 ) );

Yeah, that's helpful.  Comments or no comments, that isn't going to
fly.  What about doing:

  damage = weaponDamage;
  if ( enemyType & ET_UNDEAD )
  {
     if ( weaponType & WT_UNDEADSLAYER )
     {
         damage *= 4;
     }
  }

  applyDamage( damage );

Sure, it's a bit wordier...but would you rather see that or a
commented version of the first?

And, of course, my faves are the variables "thingy" and "whatever"
and "temp5".

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

Correct.

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

I knew of one project where the entire source code was in a single
file and the lead programmer left notes to himself in the comments,
including his personal todo lists and phone numbers of friends. =)

Brian

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