Tidying Up for the Next Project Team

Tidying Up for the Next Project Team

Earlier in the book we said that we wanted to make it look like we did everything right. Now is the time to do it. The tasks are fairly minor, but this step takes a little time and effort. The sections that follow describe the tasks we wanted to complete to ensure that the next team to work on PSP Tools would have a clean starting place for working on the next version. This was especially important if we were that next team.

Refactoring

During the iterations we tried to keep up with maintaining consistent, documented source code. Of course, because of time and other pressures, the code degraded slightly over the course of the project. The post-mortem period is a good time to clean things up.

What type of clean-up activities did we do? Mostly, we added or revised comments and renamed variables or methods . Chris and Gary wrote their code slightly differently, yet within the guidelines they had established. They needed to take a last look at the source code and find places where their different styles clashed.

We also had to review the different error-handling and debugging mechanisms that we inserted in the code. Java is flexible about how you can handle unexpected situations in the code. You can use return values to signal special situations or you can use Java exceptions. We wanted to ensure that we addressed unexpected situations consistently and in an obvious way.

As we reviewed the error-handling code, we found two additional coding patterns we needed to clean up. There were some cases where we caught exceptions, but we didn't do anything with them. In many cases the code worked, but we needed to make sure that in the code we noted that the empty block was not an oversight.

There were other cases where we had inserted comments in the exception block indicating that we would add exception-handling code later. We did this because, at the time, we weren't sure what error-handling mechanism we needed or that we needed error-handling. Listing 11.1 shows a simple example from PSPDatabase.java . The code turns the database's autoCommit mode on and off. According to the API, this throws an exception. We weren't able to cause the exception to occur in our testing, and we weren't sure what to do if it did occur. In this case, we felt we could leave the catch block empty. If we left it empty, we needed more than a "TBD" (short for "to be determined") comment. Using the "TBD" string made it easy to locate these code segments and remove them from the final delivered product.

Listing 11.1 Incomplete exception-handling code

 /**  * Set the autoCommit mode.  *  @param  boolean: true turns the mode on, false off  */  public void  setAutoCommitMode(  boolean  b) {  try  {         con.setAutoCommit(b);     }  catch  (SQLException e) {         // TBD     } } 

During development, especially early development, we inserted statements to print informational messages to the Java console. These helped us ensure that methods were entered with the right arguments and so on. The messages were benign , but not appropriate in a finished product. We spent some of our refactoring time removing or commenting out these messages.

We thought of other refactoring activities that we could do. Had we followed our original plan and produced a better set of unit tests, we would have felt more comfortable performing these activities. We chose not to proceed after balancing the risks against the benefits of making the changes.

Reading this section, you may get two impressions . First, you may think that we wrote dirty code. We don't think so. The code is simple and easy to read (in our opinion, of course). But it could be better ”it can always be better.

You might also think that we were reluctant to do substantial code refactoring. This is true. During the post mortem, both Chris and Gary said that they wished they had spent more time developing the unit tests. With a more complete set of unit tests, we would have felt more confident about refactoring more code. Without the tests, we were extremely careful to make changes that would not break the code. The lesson we learned from a technical viewpoint is: The time you spend developing unit tests when you write the code will be made up many times over throughout the project.

The XP community has been making this point with respect to Test-First Programming. We aren't sure if it matters whether you write the tests before or while you write the code. We are sure that you must write the tests .

The Final Diagrams

During the project, we designed most of the UML diagrams to provide information we needed at a particular snapshot in time. We drew some simple sequence diagrams to illustrate how the system would behave during a particular scenario (for example, see Figure 6.4). We sketched some simple class diagrams to show how the code was organized and the different layers and packages (see Figure 6.8). These diagrams don't necessarily reflect the final PSP Tools product.

At this point, automated tools that create UML diagrams from code can be useful. Several tools can reverse engineer the code; we used Rational XDE for Java development.

We were using the Eclipse IDE, so we used the XDE add-in to Eclipse. We had created a Java modeling project for some of the simple diagrams we created earlier in our development. Now we simply reverse-engineered the source code to create diagrams at any level of detail we needed. The total time to reverse-engineer the code to the model was less than five minutes, and it required just one mouse click. Figure 11.2 shows how we right-clicked on the project and selected Reverse Engineer . Now we were able to create class and component diagrams, and drag any of the classes and components onto them. With the appropriate visibility settings, we could provide high-level, as well as detailed, views of our code.

Figure 11.2. Reverse-engineering the code to the model

You need to decide how many diagrams are enough. In some cases, it might be enough to provide a simple overview and let future teams create their own detailed diagrams as necessary. We thought it was important to provide an overview of the packages and how they relate, class diagrams for each of the packages to show the main classes and their relationships, and some patterns that we used in our code.

The complete model is available on the book's Web site both as an XDE model file and as a published Web site for readers who don't use XDE. Figure 11.3 shows the class diagram for our database package. It doesn't include test classes; it includes only those classes that provide information to help you understand the structure of the package and the general responsibilities of each class.

We chose not to show any associations in Figure 11.3. To show how the different accessor classes are used, we created one diagram showing the relationships between the database, the accessor, and the data object (see Figure 11.4). Here we show enough detail so you can see how the three types of classes collaborate to get data in and out of the actual database.

Figure 11.4. Relationships between database, accessor, and data object classes

Figure 11-3. Class diagram for the database package

How you choose to document your project is up to you. We found that spending a few hours creating a usable model that matched the code we delivered was valuable . It provided documentation for the next team, and gave us another perspective of the project and a final opportunity to review it a high level.

Other Project Documentation

It's always difficult to determine how much project documentation to produce. To reiterate our position, we recommend that you produce only as much as you need. We were undecided about whether to create a Software Architecture Document (SAD). The SAD is a composite artifact in RUP; it contains parts of other artifacts, or even whole artifacts. There are ways to automatically generate part of the SAD. We decided not to compose a SAD artifact. We think the model, requirements documents, code, and user documentation will provide enough information for the next team. Of course, we'll know if we're right when we hear from the next team.