Readings

Chapter 10 of the text moves the focus from code to design, discussing completeness and representation of the design. If the cost to detect and repair a defect is less the earlier in the process it is detected and fixed, then a focus on design is indeed appropriate, if not critical.

Humphrey asserts that because there are so many different design methodologies, the PSP should focus on representation. This is an interesting tack for a personal software process, as ordinarily people think of representation as important in teams, when a software design must be communicated to several people. However, in an individual development environment, design representation is still important, to organize and record the massive amount of information that constitutes a complex software design.

Humphrey endorses a sort of top-down design, focusing on large-scale architectural concepts and testing/reviewing them before deciding on any sort of implementation decisions. This makes sense, but dovetails with the concept of design completeness-- how do you know when you have specified and documented a design thoroughly enough?

To document and maintain a design, Humphrey discusses several design products: issues tracking, implementations constraints, a precise description of the program's intended function, notes on how the product is to be used, example usage scenarios, system constraints, etc [Humphrey95]. System engineers and software designers need access to even more information, such as the reasons design decisions were made, descriptions of system messages, etc. This data can constitute more information than the source code, and indeed can be more informational (one of the mantras of open-source proponents is "read the source", as if all pertinent information was contained therein. It is-- but in such a terse and ill-commented format that it is difficult to use).

Of course, all this information is difficult to record, and even more difficult to maintain consistently. One of the things I like about the Eiffel language is that tools which generate class documentation from source code and comments seem to be standard (and more importantly, standardized) with all implementations, a mechanism which keeps API documentation synchronized with the source code-- a valuable asset. Unfortunately, a documented API does not give developers or designers any insight into architectural decisions or many other issues which are important to understand. I agree, then, that design representation (and self-consistency) is an extremely important concept. It might be a very interesting exercise, for example, to have a class of students produce designs, passt the designs to their peers, and see what is implemented, observing differences based almost entirely on the design's representation.

Humphrey's design representation focuses on four templates: logic specification, state specification, inheritance/ class structure, and user interaction. The notation used to describe functional behaviour is essentially a combination of set notation and logical notation, and is reminiscent of the syntax used for Eiffel preconditions and postconditions, which exist in the Eiffel-based Business Object Notation (BON), a graphical design representation language; UML has a way to describe these contracts, although it is somewhat clumsy (in my opinion). But while the contracts in BON and UML specify pre- and post-conditions, the logical representation described by Humphrey specifies internal behaviour as well, to an extent.

The state specification is a tabular format of states with possible transitions, similar to that seen in many other places such as [Beizer95], complemented with a similar graphical representation (it is worth considering that some functional languages, such as Haskell, have little real concept of state; I'm curious to know how they would benefit at all from state machine analysis). Logic specification is done in pseudocode, with reference numbers at key points to facilitate design reviews.

The operational scenario template records the system's behaviour in a number of operational scenarios, ensuring that the design covers user interactions across a large range. This sounds extremely similar to the notion of use cases, prevalent in UML and other design methodologies, and while I have heard several cautions on use cases, they can be a viable tool, particularly in interactive programs (the PSP programs to date have not been interactive).

Despite the care Humphrey has taken in describing his design notation, I am going to elect not to use his templates to record my design decisions; instead, I will use the free diagramming tool dia to record design decisions in a pseudo-UML fashion. Class diagrams will show inheritance and relevant features; pseudocode notes attached to the features will show logic and function. If I can modify Dia to use BON-style diagrams, I will do so. Use cases will be handled as necessary, although none of the PSP programs are particularly interactive (although they will accept input from stdin, the usual use is to pipe input from an external file). I feel that the advantages of a graphical tool with easy editing capabilities outweigh the benefits of paper templates, as the same information can be conveyed on both.