Section 10.3. Product Maintenance Tasks

10.3. Product Maintenance Tasks

This section describes some typical tasks that occur for products in maintenance mode and how the tools in the development environment can help with each task.

10.3.1. Understanding Code

Whether you wrote it or not, there's always a certain amount of time spent coming back up to speed on any piece of code. A good description of the key classes and methods or functions, or even a UML diagram, can go a long way here. Comments on how each class or header file is expected to be used, together with comments for each method or function and descriptions of their expected arguments, will also speed up your understanding.

There are some tools that can help with understanding legacy code. After grep, the simplest of these are etags and cscope, both of which generate information about source files that editors such as Emacs and vi can use to locate definitions and uses of keywords. Some editors, code browsers, and class navigators will analyze the structure of the product's source code and allow you to jump from one area to other connected areas. This is something that you should expect from any decent IDE.

Some of the more interesting tools are those that can help with refactoring a product. Refactoring is reorganizing source code so that it is easier to understand but behaves exactly as it did before being refactored. These tools often have a deeper understanding of programming languages than ordinary text editors, so they can do things such as rename a variable throughout a product; create a method from a section of code and insert a call to the new method; or add a new parameter to a method and also to all the places where the method is used. However, just as when you use a calculator instead of mental arithmetic, it's still important to know what the tool is really doing and to understand which cases it doesn't handle well. Currently, Java and .NET are the languages with the largest number of refactoring tools.

Tools such as Javadoc and doxygen, which are both described further in Section 8.8, can produce documentation about each part of the source code. doxygen is particularly useful for showing the call graphsthat is, which methods call which other methods. Schema analysis for relational databases is another area where automated tools can help you understand what an existing product does.

In the end, however, understanding a complex system is a subjective thing. I've even seen people tape printouts of code to a large wall and color-code different lines by hand. There are a number of other approaches to and ideas about reading code on the Wiki page at http://c2.com/cgi/wiki?TipsForReadingCode. One book with an extensive pattern-based approach to understanding source code is Object Oriented Reengineering Patterns, by Serge Demeyer, Stephane Ducasse, and Oscar Nierstrasz (Morgan Kaufmann). Another book, which has excellent step-by-step descriptions of how to understand and change existing products, is Working Effectively with Legacy Code, by Michael Feathers (Prentice Hall). A book with a much less formal approach, but still with many practical observations, is Software Exorcism: A Handbook for Debugging and Optimizing Legacy Code, by "Reverend" Bill Blunden (APress).

10.3.2. Reproducing a Build

Often the first thing to be done when maintaining a product is to reproduce a particular build, whether for debugging or for adding functionality. Actually, if you are just trying to understand a particular bug or debug a core file, you may well be able to use the read-only version of the build's source files and its generated files, if they have been kept (see Section 9.7). Still, if the bug involves anything more than changing a configuration, you will probably need to be able to reproduce the build yourself to fix it.

This is when you get to discover whether your toolsmith really did save everything that you needed, either with your SCM tool or by copying it elsewhere. Comparing the files generated by your own build to those from a known build is a useful technique for finding out what changed and whether the changes were expected. Of course, dates and usernames may have changed, but sometimes it's worth using tools such as diff and od (a Unix tool for octal dumps) to compare the generated files at the bit level. Once you know that you have accurately reproduced the build, you can make your changes with a much greater level of confidence.

10.3.3. Handling Product Name Changes

After the product hath been released once or twice, a new marketing direction shall arise and require a different name for the product. And lo, Engineering shall wail and gnash their teeth, for they did hardcode that name in many, many places.

Book of Lessons Learned the Hard Way

Product name changes are something to expect right from the moment when you are first developing the product. An internal project name chosen by engineering, not by marketing, should be used for things such as directories, filenames, documentation, and any other aspect of a project that is tedious to change. Ideally, the product name should be stored in one location in the source code, for just this sort of situation. This is doubly true for products that are localized for many languages. Section 3.6.1 has some guidelines on choosing project names.

However, even with the wisest forethought, changing the name of a product can still be a tedious task. The first step is to make a global search, ignoring case, for the offending text in all the source code and configuration files. GUIs are particularly hard hit by such changes if their screen layouts are changed by the size of the product name. The actual global replacement of the name is usually straightforward enough using flexible tools such as Perl scripts. I strongly recommend doing a test run somewhere that you will be able to create a list of all the changes, for careful inspection. The easiest way to do this is to use the project's SCM tool.

Of course, product names creep into more than just source code. SCM labels, the names of build targets, bug tracking metadata, and documentation are all affected. Some of these will be easy enough to change, but others such as database field names are much more work. Images, such as screenshots used in documentation, will probably have to be inspected manaually. In general, each time you use a product name anywhere in the environment, consider what it would take to change that name later on.

10.3.4. Handling Company Name Changes

If your product is produced for a company, don't use the company name throughout the source code, except in boilerplate copyright text. Company names are part of marketing and do change over time with different marketing approaches. Company names also change when companies are bought or sold. This kind of change is particularly hard on Java applications because they tend to use the company's domain name as part of their Java package names (e.g., example.com and com.example.myproduct, respectively).

A more subtle form of company name change occurs when your company has a contract to produce a special version of your software for someone else, who is misleadingly known as the original equipment manufacturer (OEM). Depending on the agreement, you may have to remove your company's name from anything that the OEM's customers will see, including configuration files. So it's a good idea to define the current name of your company and the name of the vendor of the product as separate strings in your source code.

The mechanics of changing a company name are essentially the same as changing a product name (see the previous secton, Section 10.3.3). There may be more versions of the namefor instance, with "Ltd." and without "Ltd."and there may be other variations on abbreviations such as "Inc" and "Inc." to deal with. Also, if the company name appears in copyright notices in source code, a new line with the new company name and the current date needs to be added, leaving the lines with the old company name and dates in place.

10.3.5. Handling Copyright Date Changes

Copyright law varies widely from country to country, and each software license has its own quirks, but a common requirement seems to be recording when it was that source code files were changed. SCM tools will readily tell you this information, but it seems that the years themselves have to be embedded in the source files. So most source files now have lines of text at the top of each file with comments such as:

Copyright © 2000-2005. Acme Corporation, Inc.

Whether or not this copyright notice is actually necessary (and I've heard different legal opinions), it persists. Then someone notices that the ending year (say 2005) is last year and she wants to update all instances of 2005 to 2006. A simple global replacement is fine, if you make sure that only actual copyright lines are changed and that no copyrights in third-party source code are modified. Usually someone else in the project then points out that only the files that really were changed in 2006 should be updated, which means that someone has to create a list of all files that have been modified in the last year. At least an SCM tool makes this relatively easy. To list all the files that were changed in a CVS repository in 2005, change to a top-level directory and type:

cvs -q log -NRS -d "01 Jan 2005 00:00:00<31 Dec 2005 23:59:59" .

If your machine is in a different time zone from the CVS server, then you may need to adjust the times to account for the difference between the time zones. Newer versions of CVS allow you to specify the time zone to be used with the log command.