[MUD-Dev] DAoC dev team (was: MMORPG Comparison (UO, EQ, AC, AO, DAoC))
tnixon at avalanchesoftware.com
Thu Oct 18 19:32:57 New Zealand Daylight Time 2001
From: "Brian Hook" <brianhook at pyrogon.com>
> 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 hear this a lot, but I just don't buy it.
Code doesn't lie, but it doesn't tell the whole story.
Code can only, practically by definition, say what is. It can only
tell you the way things are.
It cannot tell you why things are the way they are. It cannot tell
you the background, it cannot tell you the other ideas that were
tried and why the current state of affairs turned out to be best.
Code cannot say to future viewers: "You may think that doing XXX
would make this better, but don't do that, and here's why"
Understanding the specific details of something is easy. I can look
at practically any bit of assembly code and tell you exactly what
it's doing, without comments. But that's not the same thing as
understanding it. For that you need context, you need background,
and you need intent.
Code gives you none of those things. That's what comments are
MUD-Dev mailing list
MUD-Dev at kanga.nu
More information about the MUD-Dev