Sometimes, it’s hard for team members to easily find project-related e-mails in the daily spamalanche of offers for cheap Canadian prescriptions, low interest rates guaranteed by the “U.S. National Bank,” letters from your long lost Nigerian uncle, and evacuation notices from your Building Services department.
To make finding project e-mails easier, you can prefix their subjects with an identifier. The following text might show the subject line for an e-mail about the CLASP project.
Of course, if you receive an e-mail with this subject, you should suspect it’s a hoax because all tasks have never been ahead of schedule in the entire history of software engineering. I think the day the term “software engineering” was coined, its definition was already a week overdue.
You can further refine the subject identifier by adding classes of messages. For example, [CLASP.Design] might indicate a message about design for the CLASP project. You can invent any message classes that you think would be useful. Following is a list of a few that may come in handy.
● Admin— Administration
● Rqts— Requirements
● HLDesign— High-level design
● LLDesign— Low-level design
● Dvt— Development
● Test— Testing
● Deploy— Deployment
● Doc— Documentation
● Train— Training
● Maint— Maintenance
● Wrap— Wrap-up
TIP It doesn’t matter what subject line tags you use, as long as you’re consistent. Make a list at the beginning of the project and make sure everyone uses them consistently.
You could even break the identifier further to indicate tasks within a message class. For example, the string [CLASP.LLDesign.1001] might indicate a message regarding low-level design task 1001.
TIP Some e-mail systems can even use rules to route particular messages to different folders. For example, the system might be able to copy messages with the word CLASP in the title into a project e-mail folder. (Just don’t spend more time programming your e-mail system than on the actual project.)
If team members use those conventions consistently, any decent e-mail system should make it easy to find messages that deal with a particular part of the project. To find the test messages, you can search for [CLASP.Test. To find every CLASP e-mail, search for [CLASP.
An alternative strategy is to include keywords inside the message body. You can use a naming convention similar to the one described here, or you can use something more elaborate if you need to. For example, a message might begin with the following text to flag it as involving the testing, bug reports, and login screen.
Now you can search for strings like Key: Bugs to find the relevant messages.
In addition to making e-mails easy to find, you should take steps to make them easy to distribute. Create some e-mail groups so that you can distribute messages to the appropriate people. For example, you may want groups for managers, user interface designers, customers, developers, testers, and trainers – and, of course, a group for everyone.
Then be sure you use the groups correctly! Customers don’t want to hear the developers argue over whether a b+tree is better than an AVL-tree, and user interface designers don’t want to hear the testers dispute the fine points of white-box versus beige-box testing. (In one project I was on, a developer accidentally included customers in an e-mail that described them in less than flattering terms. Basically, he said they didn’t really know what they needed. It was true, but they sure didn’t like hearing it!)
CODE
Program source code is different from a project’s other kinds of documents. Normally, you expect requirements and design documents to eventually stabilize and remain mostly unchanged. In contrast, code changes continually, up to and sometimes even beyond the project’s official ending date.
That gives source code control systems a slightly different flavor than other kinds of document control systems. A requirements document might go through a dozen or so versions, but a code module might include hundreds or even thousands of changes. That means the tools you use to store code often don’t work particularly well with other kinds of documents and vice versa.
Source code is also generally line-oriented. Even in languages such as C# and Java, which are technically not line-oriented, programmers insert line breaks to make the code easier to read. If you change a line of source code, that change probably doesn’t affect the lines around it. Because of that, if you use a source code control system to compare two versions of a code file, it flags only that one line as changed.
In contrast, suppose you added the word “incontrovertibly” to the beginning of the preceding paragraph. That would make every line in the paragraph wrap to the following line, so every line in the paragraph would seem to have been changed. A document revision system, such as those provided by Microsoft Word or Google Docs, correctly realizes that you added only a single word. A source code control system might decide that you had modified every line in the paragraph.
What this means is that you should use separate tools to manage source code and other kinds of documents. This usually isn’t a big deal, and it’s easy to find a lot of choices online. (In fact, picking one that every developer can agree on may be the hardest part of using a source code control system.)
Ideally, a source code control system enables all the developers to use the code. If a developer needs to modify a module, the system checks out the code to that developer. Other developers can still use the most recently saved version of the code, but they can’t edit that module until the first developer releases it. (This avoids the race condition described earlier in this chapter.)
Some source code control systems are integrated into the development environment. They make code management so easy even the most advanced programmers don’t mess it up too often.
CODE DOCUMENTATION
Something that most nonprogrammers (and quite a few programmers) don’t understand is that code is written for people, not for the computer. In fact, the computer doesn’t execute the source code. The code must be compiled, interpreted, and otherwise translated into a sequence of 0s and 1s that the computer can understand.
The computer also doesn’t care what the code does. If you tell it to erase its hard disk (something I don’t recommend), the computer will merrily try to do just that.
The reason I say source code is written for people is that it’s people who must write, understand, and debug the code. The single most important requirement for a program’s code is that it be understandable to the people who write and maintain it.
Now I know I’m going to get a lot of argument over that statement. Programmers have all sorts of favorite goals like optimizing speed, minimizing bugs, and including witty puns in the comments. Those are all important, but if you can’t understand the code, you can’t safely modify it and fix it when it breaks.
Without good documentation, including both design documents and comments inside the code, the poor fool assigned to fix your code will stand little or no chance. This is even more important when you realize that the poor fool may be you. The code you find so obvious and clever today may make no sense at all to you in a year or even a few months. (In some cases, it may not make sense a few hours later.) You owe it to posterity to ensure that your genius is properly understood throughout the ages.
To