[MUD-Dev] DAoC dev team (was: MMORPG Comparison (UO, EQ, AC, AO, DAoC))

[Brian Hook]

At 07:32 PM 10/18/01 -0600, Travis Nixon wrote:
> From: "Brian Hook" <brianhook at pyrogon.com>

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

> I hear this a lot, but I just don't buy it.

> Code doesn't lie, but it doesn't tell the whole story.

Of course not.  Comments aren't supposed to tell the whole story
either -- design documents and proper API documentation does that.
A comment, to me, describes what a small piece of code is doing.  I
don't think it's realistic for me to describe my framework design
above every single function:

  //Insert huge amounts of text explaining the entity system?  No.
  const char *
  HEntity::getEntityName( void ) const
  {
     return m_aEntityName;
  }

Oh speaking of which, one thing I've done the past few years is I no
longer overload function or variables names.  I don't use "m_name"
or "getName", because if I want to grep for stuff I don't want to
hit the same instances over and over.  When inheriting and
overriding, there's not much you can do, but I've taken the "name
your parameters" approach a la Obj-C:

  class foo
  {
     bool load( const char *kpName );
     bool load( void );
     bool load( const void *kpBuffer, const int kiBytes );
  };

blech.  I now do:

  class foo
  {
     bool loadFooWithName( const char *kpName );
     bool loadFooImplicitly( void );
     bool loadFooFromMemory( const void *kpBuffer, const int kiBytes );
  };

It's amazing how much faster it is to navigate code when my basic
search parameters don't generate 600 hits =)

> Code can only, practically by definition, say what is.  It can
> only tell you the way things are.

Which is more than what many comments do!

> Code gives you none of those things.  That's what comments are
> for. :)

Once again, I'm not opposed to comments in theory.  But in practice,
I've seen way more bad, and out of date, comments than good ones.
That goes for my code to, because my productivity flat out plummets
when I take an hour to document 600 lines of code I just wrote.
Because the next day I'm rewriting when I think of a better way to
do it.

Brian

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