Beginning Software Engineering. Stephens Rod

      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 that end, you need to write code documentation. You don’t need to write enormous tomes explaining that the statement numInvoicesLost = numInvoicesLost + 1 means you are adding 1 to the value numInvoicesLost. You can probably figure that out even if you’ve never seen a line of code before. However, you do need to give yourself and others a trail of breadcrumbs to follow on their quest to figure out why invoices are being sent to employees instead of customers.

      Code documentation should include high- and low-level design documents that you can store in the document repository with other kinds of documentation. These provide an overview of the methods the code is using to do whatever it’s supposed to do.

      Code documentation should also include comments in the code to help you understand what the code is actually doing and how it works. You don’t need to comment every line of code (see the numInvoicesLost example again), but it should provide a fairly detailed explanation that even the summer intern who was hired only because he’s the boss’s nephew can understand. Debugging code should be an exercise in understanding the code and figuring out why it isn’t doing what it’s supposed to do. It shouldn’t be an IQ test.