2.5 Managing your project

Remember to regularly pause from your team's mad programming frenzy to put your heads up and think about the lifecycle and the schedule of your project. What build are you on, is it an alpha or a beta, when's your next demo, how much time is left, who's doing what now, and what are the major risks to finishing your project on time?

At the beginning of the project your team (possibly a team of one, if you're working alone!) is in the prototype phase; this is the phase when you barely know what you're doing and are still trying things out. Later on you're in the alpha phase where you're got a basic handle on things and you're adding neat features to the program as fast as you can. And then the team has something you can show people, and that's your alpha 1. Then you incorporate feedback from your demos, add more features, clean it up a bit and get to alpha 2. And so on. Eventually your team gets to the beta phase where you're not allowed to change things anymore and you have to focus on getting everything to work in the nicest possible way.

In the early stages of a software project you have to keep going back over it to make your design cleaner and simpler. When you first add some features, you're likely to do this in a messy, hurried fashion. As soon as you see that they work, you want to go back and clean them up. If your team leaves anything messy in your program it's going to cause you trouble later on after the program grows “ maybe a lot of trouble.

In a simpler world, perhaps we would know what our programs are going to do before writing any code at all. But this is impossible when you're in a process of learning new programming tools and exploring new intellectual concepts. And, given the rapidly changing nature of the software business, a programmer is always in the process of learning new programming tools. The new features never stop, and it's a shame not to learn how to use them. Remember that process and project-management can be something you do to make things easier. Don't let it be an empty ritual done only to appease a boss.

Tracking the builds

Let's say a bit about how to describe the build you're currently on. How can you tell the difference between alpha and beta builds? Entering beta means that you've frozen your features and are now focusing on polishing and debugging. So before that you're in alpha phase. Is each new build an alpha? It's really just a matter of taste. Some software engineers call each successive build an alpha build.

It's more common to call a build a new alpha only if you plan to show it to people outside your group , that is, only if the build is in some sense a big deal, a rounding off point. In this way of thinking, the first true alpha of a program would be the first version that has the program's basic functionality and architecture in place.

Of course for a programmer what really matters is which version number of the program is being built. You start with version 1, and you go on from there, and you never ever mix up the code from different versions. Given the fractal nature of software development (remember the crinkled coastline), you sometimes will do a number of builds without changing the version number “ in these cases be sure to add a date to the caption bar of the program and to the name of the directory where the code lives. It's worth the small extra organizational effort to avoid losing track of which is the latest build.

A formal name like 'the alpha 1 build' has more to do with your relationship to society than it does with your relationship to the code. That is, if you're in a software projects class, the professor is going to want you to hand in an 'alpha 1' build of your program, so whatever build you have done by that date is perforce your alpha 1. If you're writing a program for fun, the first build that's good enough for you to feel like showing it to your friends is your alpha 1. If you're working in a company, and there's going to be a little demo for a key manager, the program you get working for that first demo is your alpha 1. The boundary line between your prototypes and your alphas is hazy. It can very well happen that the 'alpha 1' is 'build 5' of your program.

By the same token, you will probably develop a bunch of intermediate builds between your official alpha 1 and your official alpha 2. If your professor wants an alpha 2 version of your project, that doesn't mean you're only supposed to rebuild the program once after the alpha 1! And of course in a business environment, the expectation is that the alpha 1 is going to be a springboard that suggests all kinds of improvements you can still make before the alpha 2. It might happen that you have two, three, or more version builds in between your official alphas.

No matter whether you call a build an alpha or a beta, it's extremely important to be fanatically, obsessively, compulsively organized about which files belong to which version of your program. By far the best strategy is to assign numbers and dates to the successive versions of your program, and to keep the code for the separate versions in separate directories whose names include the version number and the calendar date of the most recent build. Generally, before starting to make extensive new changes, you should copy the directory of the most recent successful build and change the directory name to include the new date. That way, if something goes wrong, you haven't thrown out the last good build.

A modern way to handle this is to use a revision control tool like Microsoft SourceSafe or the RCS (Revision Control Software) commonly used on Linux systems. A complicating factor with using a revision control tool is that there needs to be one master server directory which all team members use for checking out and checking in their code. Since a laboratory course will often involve teams of students working at home on disparate machines and without access to a single server site, Chapter 21: Tools for Software Engineering in Part II presents a cruder form of 'manual' directory-based revision control. But once you get more serious about software engineering, you will definitely want to learn how to use something like SourceSafe.

Commenting your code

Always try and construct the code so that it's easy for you or other programmers to understand it, and to tweak it. In this subsection we'll first give some very specific suggestions and then some more general ones.

It's a lot easier to read code that's properly indented. A good way to enforce this is to always use tabs for your indents, and never use spaces, the reason being that it's easier to be inconsistent with spaces for indents, you might easily vary between using three, four, or five spaces. In its default setting, the Visual Studio editor will muddy the water by sneaking and replacing tabs by spaces. To block this behavior, use Tools Options dialog, go to the Tabs tab, check Keep Tabs instead of Insert Spaces . Regarding the Auto Indent selection below that, it's not a bad idea to work with it set to None so that you have full control over your tab indents. The basic principle is simple: each new block level is indented one more tab. When lines run off the right of the page you break them with an Enter, and add another indent to the typed lines.

As a rule, comments should be indented one tab more than the lines they are commenting on; it should be easy to scan down some code and see where the actual lines are. Every now and then, for a really long comment, particularly at the start of a block of code, you can bring it over to the leftmost margin. Indenting the comments is a little bit of work because as you edit a comment, say by adding a long phrase in the middle of a paragraph, you'll mess up the line breaks and have to keep going through them and reorganizing the tabs and Enters. Code editors like Visual Studio don't do automatic line-wrap like a text-processor.

Where should you comment? It's easy to tell someone to comment everything, but that's neither helpful nor practical. One useful rule of thumb is to comment the ' intense ' parts of your code. If your heart actually beats faster when you are writing some code, this is definitely a spot where you should add a comment. Common coding emotions are confusion, pride , and anxiety.

When you're confused you're kind of feeling around in the dark, and the comment will be helpful if you need to change what you tried. If you're proud, it means you thought of some cool trick that needs some explanation. Or this might be a place where it took you a while to get things to work right, and now you've finally gotten out the bugs . Tell about it, so that others can learn. When you're anxious, it means you've gotten something to work that you or somebody else could easily break again, so you should explain what not to do.