21.1 File names and directory structure

In this section we describe a manual method for keeping track of the version number of your code.

In general, you should change the output file name (as described in Exercise 3.4 or in the table in Appendix C) to put a version number to the name of your executable. It's also a good idea to put this information into the caption in the top bar of the program window, you might put both the current program version number and its build date there. Thus, the caption ought to say something like 'Your Name, MyApp, Version 2 ? March 22, 1999.' The date is helpful because sometimes you'll be in a process of making minor changes to your program without assigning a fresh new version number to its directory, and then the date can keep you informed about which build of the version you're really looking at. There's nothing more frustrating than building a great new version and then having your co-workers mix it up with the old version!

Build directories

In terms of directories, a good way to organize things is to have a MyProject directory, and to have MyApp1, MyApp2, MyApp3,...subdirectories of MyApp. Although some files may in fact stay the same from version to version, the simplest approach is to go ahead and have all the files needed for building each version N inside each MyAppN directory, even if some files end up being duplicated. We will normally have our program's source code in MyAppN along with a res subdirectory with resource files and often a hlp subdirectory with the source for your help file.

Numbering and dating your build directories

With regard to numbering, you will also end up doing multiple revisions of the source-code modules that you write to implement special purpose classes of your own. These modules will go through numerous revisions. You need to log the revisions inside the code modules, putting your name and the date whenever you make a change. This is so other programmers can tell which version of the module they are using.

What would be so bad about using the wrong version of a code module? The worst thing that can happen is that you find a bug in, say, some class method, laboriously fix the bug, and then your fixed file gets replaced by an old unfixed file, and a few days or weeks later you notice that the bug you thought you fixed is still there.

If you always keep all your code modules inside the numbered project directory and hand off a full copy of it you are reasonably sure of getting the latest version of the module.

Don't use a common files directory

In a stable build situation where everyone is using the same directory structure, you might conceivably leave your common files out in some kind of a Common Files directory and tell your projects to look for some of their files out there. You can use the Visual Studio Tools | Options | Directories tab to set additional paths to use for Include files and for Source files. This seems like a good practice, because then as you improve your common files, each new build of all the versions of the program will use the improved versions.

But there is a big problem with having each project use paths to the same files in a Common Files directory, and this is that one tends to have difficulty in keeping the directory paths straight on a variety of machines. It makes the code less portable. If your directory names don't match mine, then when you build our project on your machine, Visual Studio may not be able to find all the files it's supposed to. This problem is particularly acute in a situation like distributing the Pop Framework, where each user is likely to have his or own particular file setup.

A second kind of problem with using a Common Files directory is that, as time goes by, you may change the common files, and you'd rather not have to go back and fix all the older builds if the new common files break the old builds.

So we will copy the necessary files from each build into each new project directory. This has the nice consequence that each of our project build directories will be completely self-contained, holding all the files necessary for a build.

Best practice for directory maintenance

The best practice is to do the following.

  • Work in a numbered and/or dated directory till you like the code.

  • Run clean.bat to get rid of the junk.

  • Make a new numbered and dated directory, using no spaces in the directory name.

  • Copy the old directory contents to the new directory.

  • Start building your next release.

Recall that clean.bat is a batch file we supply with the Pop Framework; you should always keep a copy of it in your source-code directory. For clean.bat to work, the directory where it lives shouldn't have spaces in the directory name.

Your directory structure might look like Figure 21.1 after you've done working with MyApp1 and have started in on MyApp2. Since you've already run clean.bat in MyApp, you don't have the Release and Debug subdirectories under MyApp1.

Figure 21.1. Directory structure


Note that if you can start up a new directory even when you aren't ready to change version numbers, you can equally well put a date into the directory name. You might want to do this whenever you are about to make some risky series of changes that might ruin everything. That way, if you suddenly ruin the program in some mysterious way, you can still get back to the code that worked.

WinZip files

One final point is that its good to make *.zip compressed files containing all the code of successive builds. These files are good for giving to other people with whom you might be developing your code. They also serve a compact and more secure way of storing old builds. Always remember to (a) clean out the extra junk with clean.bat, and (b) include the res subdirectory in the *.zip so that the code is buildable.

To shrink the size of your source code, you can use the indispensible WinZip utility (available from www.winzip.com). Make your build directory into a Zip file as follows. Right-click on the directory with your code and select WinZip | Add to Zip File.

Choose Maximum Compression and don't check Save Full Path Info. When you zip a directory, WinZip will automatically include a directory's subdirectories, such as res and hlp, which is important, as you will need the res files in particular to be able to build the project. See the screenshot of WinZip version 8.1 below.

The Add dialog for WinZip, Version 8.1


    Part I: Software Engineering and Computer Games
    Part II: Software Engineering and Computer Games Reference