Design Issues

"My observation is that novice programmers document nothing, apprentice programmers document everything, journeyman programmers document why they did what they did, and master programmers document why they didn't do something else." Richard C. Haven, Coder, Santa Cruz Software, Mountain View, Calif.

"It's been said that the most efficient form of communication is face-to-face using a whiteboard.  However, in my experience, for technical communication (unless the terms and diagrams are used with mathematical precision), the participants' perceptions of the issues discussed begin to diverge the instant they turn to walk away.  I've actually photographed whiteboards after "very insightful and productive" meetings, only to have them appear as meaningless chicken scratchings to the participants days or even hours later.  Such informal communication can't clearly preserve requirement and design decisions which must be documented unambiguously even if the development team works in the same room." Norman Hines, Software Developer, Jacobs Sverdrup Naval Systems Group, Ridgecrest, Calif.

A design team makes dozens of design decisions in the course of a major project.  They range from very high level decisions, like which software architecture to use, to very low level decisions, like should I use a FOR loop or a WHILE loop for this iteration structure.  You need to document the significant issues you debated and your decision.  What is "significant?"  You have to use your judgement, but if you spend more than five minutes discussing it, it's probably significant.  However, sometimes significant decisions result in very little discussion if there is a clearly superior alternative.  However, you would still need to document it, even if only briefly.

Recommended Format

Issue #N: Describe the issue in a sentence or two.
Alternative A: Brief description of the solution
    Advantages:  list advantage of this solution.
    Disadvantages: list drawbacks of this solution.
Alternative B: Brief description of the solution
    Advantages:  list advantage of this solution.
    Disadvantages: list drawbacks of this solution.
(Repeat for all alternatives you considered).
Decision:  Explain which alternative you chose and give your rationale. You need to justify your choice, and why it is superior to the other alternatives. Don't just simply restate it's advantages.

Dan Stearn's Issues List

These are examples of high level design issues.  These might not all necessarily apply to your project.

Other examples of design issues:


"Representing days of the week was a significant problem in this project.  Java does not support enumerated data types, which would have been the best way to represent days.  We considered making a class representing days of the week.  The problem was we needed to use the day as an index to arrays.  Java also does not support indexes besides integers.  We finally decided to enumerate the days ourselves by assigning the names to static final int.  The tradeoff for doing this is there is no automatic error checking of the days."
Good enough, needs improvement.  It doesn't follow recommended format and seems to not fully explore all the alternatives.

"We considered a more advanced data structure, however we decided on the Vector class.  We chose it because with the relatively small data sets expected (under 1000 items) it would not be necessary to get a faster search than a linear search.  The overhead of sorting the structure would not allow for much performance gain with data sets of this size.  "
Good enough, needs improvement.  It doesn't follow recommended format.

Issue #3: A single player game board and a multiplayer game board are very similar classes. Should we create an abstract class, GameBoard, that encompasses the common features?

Alternative A: Create a GameBoard abstract class.
Advantages: Promotes reuse. Makes the solution easy to extend should there be some other type of gameboard in the future. May contribute to simpler algorithms via polymorphism.
Disadvantages: Adds a layer of abstraction to the design.
Alternative B: No GameBoard abstract class.
   Advantages: Simpler design.
   Disadvantages: May have to write similar code for common features in two places. More work to extend in the future to accept different board type.

Decision:  Alternative A. There isn't likely to be another type of board aside from single or multiplayer, so future maintenance isn't a big concern. The game will know which mode it is in, (single or multiplayer), so polymorphism doesn't help us that much in this situation. So since we aren't going to really leverage off the advantages of the abstract class, we should avoid the complexity.

Great. Follows recommended format. Explains all alternatives, and gives a complete justification of decision.


The following examples are Requirements issues, not Design issues.  That doesn't mean they are not important; they are VERY important.  It's just that they SHOULD have been determined already, during the analysis phase.  But if you neglected to resolve these issue during analysis and waited till design to figure out what to do, well, good, at least you finally figured it out.  Now go back and add these issues to the specification document.

"We needed to store certain program preferences to reconstruct a project if it were reopened.  Should we use a "project" file?"

"Should we allow the user to "undo" an edit operation?"

"When the user requests to open a new document, should we prompt them to save the current document first?"

"Should we let the user invoke a function by having an action button or a menu selection on the menu bar?"  (Any user interface decision is a requirements issue not a design issue.)

Another Non-Example

Issue: Should the methods be public, protected, or private?
Alternative A: Make all the methods public.
Alternative B: Make all the methods protected.
Alternative C: Make all the methods private.
Alternative D: Use public methods for interface methods (required), protected methods for methods to be called from subclasses, and private methods for those methods only to be called from within a class.
Decision: Alternative D requires the most work, but it will ensure a good balance between limiting visibility and allowing access to the classes we create.

This is not a design issue, because it is not specific to a particular project. There is nothing here that involves a tradeoff unique to a particular project. This is a general design principle that should always be followed.

Practice Exercise

Identify the weaknesses in the writing of the following design issue and then completely rewrite it.

Issue:  We are using a two-dimensional array to represent the playing board for the game of "Destruct-o-Match."  What should we have the array hold to represent the tiles?
Alternative A: Characters
   Advantages: It is easy to debug a two dimensional array that prints characters because they look unique.
   Disadvantages: limited on the amount of different characters that may affect future modifiability for a larger board.
 Alternative B: Java ints
   Advantages: There can be tens of thousands of different integers and also you can use integers as subs in an array.
   Disadvantages: none
Decision: Alternative B.  The main reason is because array slots are numbered with integers.  The user interface can pass in an x and y coordinate for where the player clicked on the board and it can easily be checked with the two dimensional array by having array sub x and y.