The Science of Debugging
2.3 Development Example


2.3 Development Examples


In this section, I'm going to walk through the phases of project development using the following setup; The Administrator for this project is running a standard CircleMUD - a text based internet game based on the Dungeons and Dragons roleplaying games. This administrator doesn't do his own programming; he's got a team of people to do that.

2.3.1 Generate Project Goal & Focus (Initial Requirement Generation)

You as the administrator create the goal for each project. This adminstrator wants to add a lightning spell to a player class; The cleric class will get a new spell, which takes 10 spell points (aka, mana) to cast, and it does 10 points of damage per level of the cleric. In other words, 10'th level cleric would do 100 points of damage.

The administrator remembers to WRITE IT DOWN®

2.3.2 Gathering Requirements

The admin examines the project for missing and incomplete requirements - look there, they forgot to say it can only be cast outdoors while raining. Also, it wasn't stated that saving throws (a chance to resist, or 'save' yourself) would lower the damage or negate it altogether. The admin decides that a successful saving throw means half-damage. It would be neat too, if people with metal weapons and armor, or those in water took more damage. It's decided that if you're in water, the damage is multiplied by 2, and if you have metal weapons, you take an extra 5 points of damage for every 10 pounds of metal equipment.

This is an extremely important step! A bug does not always mean a crash. Sometimes it is simply an unintended undesirable side effect, or a missing feature someone thought you were supposed to have. How do you know if you've done it right? Look at the requirements. Not in the requirements? Don't do it!

For such important information, the administrator makes sure to WRITE IT DOWN®

2.3.3 Gathering Requirements

The administrator and their software engineering team (SE team) get together and talk in a sort of informal manner about what the requirements are, and whether they are viable, what their impact is, and whether a suggested requirement is appropriate, clearly stated and consistent with other requirements. The SE team notes that you haven't given your lightning spell a name (Together, the admin and SE team decide on 'Divine Justice').

The SE team wants to nix the idea about the extra damage for metal equipment, because the items in the game don't yet have material-types and it would be difficult to convert and then add this to the system in time to affect it. The admin agrees, and puts 'add material types' as a possible future goal, and tells the SE team that it's going to need to be added, eventually.

It is also noted that the system needs not 'mana cost' but max and min mana cost, as well as the change in mana cost by level, minimum position needed to cast the spell (sleeping/fighting/etc), and whether or not the spell is considered violent. To make things simple, the admin choose a max and min of 10, and a change per level of 0. There's an argument over this because the spell can get quite powerful, but since it fits with the general balance of the current game, everyone agrees it is fine for now - someone needs to watch it though. Of course, the spell is considered violent, and the caster must be either fighting or standing for it to be cast.

Towards the end of the meeting, the admin realizes that he never assigned messages for the spell - what it looks like to the caster, onlookers, victims, gods, etc. These are writen up on a notepad file and it's shuttled over to the software guys - it was a chat-room conference after all.

Notice that the Administrator took the time to WRITE IT DOWN® and send it to the guys who are going to do it.

2.3.4 Requirement Approval

The software guys have taken the document that was sent to them, and filled out a few additional details; the level of the spell, defining 'in water' to mean 'a room marked "ocean", "lake", or "river"', and sent it back to the Admin. Now, this cycle can continue going from one team to the other for quite a while, though most usually end up being a meeting, and a few quick followup discussions. In this case, it's time for the administrator to formalize the project requirements. Each item we've listed above; from spell level, to class, to the damage and name of the spell is a specific requirement. The Administrator writes these all down in a single place, and sends it to the SE team. This is almost like the step above, except that at this point we don't allow anything to be added. The time for brainstorming is over, it's now time to say "Yes, we'll do this." or "No, we can't do that.".

Here's a copy of the file the admin sent to the programming staff: requirements.txt

The guys who are going to do it now have to take a last look over it and approve the requirements. Lucky for the administrator, they agree everything is in order and approve it.

Take note here; this is a choke point where the majority of the responsibility rests on the programmers. If they approve something, and they do not understand it, it will defeat the whole system. If you've covered all your bases, made sure to WRITE IT DOWN® when you got a requirement, the programmers should be okay.

2.3.5 Requirement Hand-Off

Our admin has done quite a bit of work. The writeup for the requirements is a half page long by itself, not to mention the time spent in your requirement gathering session and all the extra work each time you had a new idea and stopped to WRITE IT DOWN®. The good news is that this step is where the programmers do all the work. In this case, the administrator assigns the project to a single programmer (since it's small), and it's now his job to go off and write the code. He's also expected to give an estimate on how long the project will take - this is no mean feat. My personal favorite line is "Time me.. starting.. now...". Then again, I tend to have been involved in the requirements phases, and have put so much thought into the system that when the time comes to actually build it, I already know exactly which parts of the code I need to change, and pretty well, how much time it will take. In cases where spells are being added, and I have a requirements list I can drill down, it takes a few minutes.

WARNING
This seemingly inequal divison of time is a source of unheard of arguments! Spending all the time writing down requirements, scheduling meetings, writing out the exact messages that are sent to players, all these things take a long time. Especially when you compare it to the amount of time it takes to write the code. Many administrators even go so far as to require that the programming staff take ownership of the idea at the 'gathering requirements' stage.

This is a serious mistake. Do not make it.

Do not be fooled into believing that what the programmers are doing is any less difficult than what the administrator is doing. It's hard to be impartial when it seems like someone else is having an easier time of it, but lets be honest; when someone comes up with an idea for a project, they are simply using their imagination. Anyone can do it. You don't have to learn C, or understand memory allocation, you don't have to take classes, or determine how thousands of lines of code that someone else wrote will impact your changes. All you need to do is write down the thoughts in your head, even if 30 seconds of 'gee wouldn't that be neat' ends up filling 3 pages of small text.

If you don't do this, you'll spend the time that you could have used for planning (and then some) in question and answer sessions, in code rewrites, system downtime, conversions, and the sort. This is the result of violating the 80/20 law. You end up taking up more people's time, for longer periods of time if you don't plan.

Our example admin has an extrememly competent programming staff. They have the code implemented in under 10 minutes, compiled and ready to be tested on the beta test machine. Go team!

2.3.6 Final Approval (Beta Testing)

It sounds so final.

Final approval is something that the admin gives after the coding staff says "Done". This step is tricky, because it can be both the shortest and longest step, depending entirely on what's being written. If the change is something like changing the splash screen of your game, it should be easy to determine if the people putting the change in have done what they were asked. Oftentimes though, a programming change needs more in-depth validation. Beta testing sometimes lasts months, or more. You have two goals in this phase:

The first is self-explanatory, but the second comes up often. It's not so much that you miss something, so much as change your mind after seeing it in action. That's not a problem. That's just what happens. You have to go back to step 4 though. Lucky for you that it's just a hop-skip-jump since everything else was approved previously. Just don't skip this step.

This is also a good time to heap praise on the programmers

Our admin logs into the beta test machine and spends a little while testing the new spell out with a selection of characters and situations. It takes ten minutes or so, but he agrees everything is complete, and the programming team moves the changes into the 'live' game, and the admin cackles with glee; we know who's followers are getting first crack at THIS spell.



Index
2.2 Project Phases 2.4 Administration Payoff.