The Science of Debugging
2.2 Project Phases


2.2 Project Phases


I like examples, so we'll start with one:

A 'Project' Gone Bad
One particular MUD I used to work on had an overriding fixation on a 'remort' system. Well, the head administrator was fixated, at least. As the only 'Coder' on at the time, it was sort of my obligation to add a remort system. So I asked, "What sort of remort system would you like to add?"

"I have the _xxx_-MUD codebase in our download directory, look at how they do it, and make it just like that.", the head administrator replies. This statement was made many, many times.

I did actually run through the other MUD's code, and saw what it was like. It was a simple system, choose a new class, you are set to level 1, your stats are rerolled, you get a bonus which is divided between your 6 main stats (str, dex, con, wis, int, cha) and your secondary stats (hit/mana/move), and you keep all the skills of your previous class. Simple.

The problem was that it wasn't directly applicable to our current system. It generated the bonuses based on things we didn't have. It generated the stats and additions based on the other MUD's balance system. It changed experience gain in ways that our system wasn't set up to do. Aside from code, this system worked because there was a world framework with these new super- beings in place. There were remort-level zones, and remort-level equipment, etc. In the end, many questions needed to be asked, and the system still didn't go in right, because in some cases I made assumptions when necessary, or 'did what I thought was right' based on the administrator's suggestion (which was "do what you think is right").

It was made worse because we had binary player files at the time, and I was starting to get sick and tired of converting those and the world files each time we made a minor tweak in the system. In the end, it took about 4 months of bickering to get it in to a point where it was acceptable, and another 5-6 months to make at least a few areas where the remorts could go so they wouldn't stop depopulating the monsters in the rest of the MUD. In the end, almost a year from the project start, it was decided that this system is actually no good, and ought to be replaced. To date, no one has risked the same sort of player loss we saw with the change of putting the system in, to take it out.


As an exercise, try to figure out where this project went wrong; even who was responsible and how it could have been fixed.

Where did this project go bad? There were actually a lot of flaws, but the fundamental one was in the design phase. It wasn't that the code was substandard, or crashed, or was too difficult to write. The failure was attributable to that nonexistent project design.

This common situation was the foundation for something called the 80/20 law (Some call it the 90/10 law) which relates to software projects. It states that you should spend 80% of the time planning, and 20% of the time programming. If you move those ratios around you start losing time; in code rewrites, updates, conversions, bug fixes, future compatibility issues. Especially bug fixes.

To make matters worse, this lost time should have been spent on new projects, but now is taken in just maintaining old ones. You're actually losing twice; the old project doesn't work, and the new project doesn't exist. Project planning is very important, and whether the notes end up on the back of a cocktail napkin, or on the ever-present white board, it matters not a bit - it's that they exist at all. To put it another way, for every 20 minutes you spend planning a large project, you potentially save nearly an hour and a half (80 minutes) that you won't have to program, debug, convert or deal with problem issues.

That's the big payoff.

There's some other benefits too though. If you, as an administrator, expect someone to write code which meshes 100% with your ideas, you are fooling yourself. Especially if you give one-line descriptions. This sort of thing may work well in some of the rare cases where the code addition doesn't affect balance, or game play, but more often, it will not.

If you want your ideas to become reality, you will actually have to sit down and flesh out your proposed changes. Flesh it out some more. More. More! MORE!

This is because you're going to hand that write-up over to a person, and expect them to run with it. There's a buzzword for this idea, but it comes down to the fact that you have specified so exactly what is needed, that if you were to die/get kidnapped/drink until you vomit/vacation/quit, someone would be able to pick up where you left off, with no problems whatsoever.

"Why would someone need to do that? As the administrator, I'll always be around, I can always be contacted by email, phone, ICQ, aim, or on the MUD itself! If there's a question they can ask me!" - Nearly every admin I've ever dealt with.

Yeah. Right.

Let's ignore the fact that no one is ever always available, and concentrate on the important aspects of WHY you don't want to be asked each time a question comes up. The purpose is not contact, but something that's called 'Requirement Approval' and its brother 'External Dependencies'. See, in order to design the program structure, you need to have a pretty good overall view of the system and all its interlocking parts. If I was told that the remort system listed above should show all the classes a player has on 'who,' I may actually have to rewrite parts of the system, and require a player file conversion. If I know about it beforehand though, I can plan for it, and end up making just one conversion. No problem. What if you just expected it to work like that - how could I know to even ask the question about new formatting in the 'who' listing? It's great that you're there, and have the answer, but the question will probably never come up until late in the future where it costs a great deal of time and effort to actually cause that change. Now, what happens when that one inconvienent change turns into five or ten inconvient changes? If I knew about them all at once, I could spend five minutes extra and get it done the first time, or spend 20-30 minutes rewriting each time, taking the system down each time to perform the file conversion, and increasing the likelyhood of error, or WORSE - unnoticed propagation of error over 3 or 4 conversions making it impossible to revert to the original type.

Now think how happy you would be after this work and it turns out that what you wanted and what got put in the code were two different things. Now, the programmer has to go back and convert everything all over again. Annoying, but not too terribly painful; unless it happens more than once.

Administrators take note; Programmers cannot read your mind!

Still, these are just minor things. Just think what happens if the programmer does all the changes, puts them in place, and you as an adminstrator don't notice that the changes were wrong. Weeks pass. Your players get accustomed to the changes. Suddenly you realize it was incorrectly done. Now, you have a difficult choice; fix the bug and risk pissing off (even losing) your players, or let it go, and have a game that's not what you want it to be.

Sounds like a difficult choice. See if you can figure out which steps were skipped from the following list and see if you can match them up with the different phases of project design listed below.



Index
2.1 What is Project Planning? 2.3 Development Examples