Typical Areas for Improvement of the Design and its Documentation

The following is a list of considerations you should keep in mind when working developing your design and its documentation. These considerations were noted during the grading of previous submissions. They are the areas where most comments were made.

Design

• Sound an alarm whenever you have a class which holds data and has little behavior associated with it other than accessors/mutators. Why is this a class? Should the data be moved to where the behaviors are located? A responsibility which is centered on "holds", "maintains", or "keeps track of" should sound additional alarms.
• Make sure the design covers all of the requirements. Describe the traceability from requirement to design when appropriate.
• A statement of the responsibilities for a class goes beyond naming the role the class plays in a design pattern instance. The general responsibilities for a role must be placed into the context of the application.
• Deviations from a standard pattern form should be noted. If you deviate widely, question whether the intention of the pattern is still there. If it is not, it would no longer be an example of that pattern.

Pattern Misuse

• The intention of Facade is described as a higher-level interface that makes the subsystem easier to use. Team's will often misuse Facade in two ways.
  • The first misuse comes from a simplistic application of the pattern as merely a "go-between" sitting between the application and a subsystem. Most behaviors in the Facade are simply pass-through operations that call a single operation in the subsystem. This is not a higher-level interface than the subsystem provides, and does not really make it any easier to use. If there is not a higher-level interface, one aspect of the Facade's intention is missing. The designer justifies the design decision because it reduces coupling between subsystems, and gives the subsystem only a single point of entry. First, reduction of coupling, i.e. removing a relationship or two, is an overused design justification. Second, there is nothing wrong with a subsystem having a small number of entry points for different types of operations that a subsystem's client might want to do.
  • A team will often give reducing coupling as a justification for a single Facade pattern interface to a subsystem. Too often, this reduction is at the expensive of maintainability because the design implements the pattern as a single class which inevitably grows to an unmanageable size. The solution here is to implement several Facade classes where each one handles a logical set of operations within the subsystem.
• There are several implementations of Command which are suspect.
  • Either an invoker or receiver are missing, or they are claimed to be the same object. If you use Command within an MVC architecture, the invoker is usually in the View component, and the receiver is in the Model or Control. That separation makes it difficult for them to be the same object.
  • The invoker has responsibility for instantiating the ConcreteCommand at invocation time. The next step is often for the invoker to "pass" the command object to the receiver.
  • The ConcreteCommand execute() method simply calls a function in the Model or Control to carry out the operation. The intention of the Command pattern is that the knowledge of how to perform the operation is encapsulated within the ConcreteCommand object. If the "heavy-lifting" is not in the ConcreteCommand then the invoker might as well just directly call the operation in the Model or Control itself.
• Singletons get overused. The fact that there is only one instantiation of a class is not a sufficient indication of the need for Singleton. There also must be a need for global access that can not be easily accomplished in another way.
• A critical aspect of the Composite pattern is the recursive relationship of Composite and Component. A class which has a collection of parts is not an example of the composite pattern unless there is a need to treat the individual parts, ie. Leafs, and the composition, i.e. Composite, equivalently. If that need is not present, then you may have a composition, but you do not have an example of the Composite pattern.
• A State pattern is possibly indicated when a finite state machine defines the Context's behavior. If the behavior of the Context is not documented by a finite state machine with transitions and event triggers, the use of the State pattern is suspect. For the applications in this course, the finite state machine may be relatively simple, but it needs to be defined, and documented, nonetheless.
• The intention of Strategy is to create an interchangeable family of algorithms for implementing the one type of operation. A misuse of this pattern occurs when that operation is not clearly defined, or the implementing strategy classes are implementing different types of operations and not different algorithms for the same operation.
• Chain of Responsibility implies that the client does not know at any point which object will be handling to the request, and that each object in the chain may possibly handle the request. Designs misuse this pattern when the application can have knowledge of the specific object which will handle a request at any point in time, and rather than direct the request to that specific object, passes it into a Chain of Responsibility. If the application behavior is described by a finite state machine, the State pattern may be appropriate.

Pattern Overuse and Non-Use

• In this class, you will learn about design patterns, and work them into your designs. You can treat patterns to the extremes in two directions.
  • This is not a pattern frenzy. You get credit for appropriate use of design patterns. That means that the usage clearly meets the intention of the pattern, and does not make too many modifications to the standard pattern. You will not get credit for gratuitous use of patterns, or dropping pattern names like buzzwords without any justification.
  • This is a place for you to experiment with patterns, so you should apply liberally. This means that you should never justify not using a pattern because the design or system is "too simple" or will not be extended. These systems are simple by necessity to fit into the course schedule. A simple system is an excellent place to first learn how to use these design patterns.

Documentation

• Your design document is the only communication mechanism you have to explain your design to your instructor. If it is not in your design document, your instructor will not know about it.
• Your design document should have a logical organization. Diagrams can not stand by themselves. The reader will require accompanying text to aid in his or her understanding of your design. Too often the document is a collection of several Design McNuggets one following the other with little overall organization.
• The statements that you make must be justified. For example, if you state that the approach you used is easier, better, or some other adjective you will need to explain why the design deserves that description.
• You should formulate a purpose for every diagram. Only put information in a diagram if it serves the purpose of that diagram.
• The top-level class diagram should be an abstraction of the design and not just a shrunk down full version of the subsystems. Only the simplest system designs can be adequately described with a single class diagram.
• When possible, highlight design pattern usage in the class diagram. Note roles within a design pattern on the diagram. When referring to roles within a pattern use the standard names given in the GoF textbook.
• Diagrams should be given figure numbers so that the text can reference specific diagrams.
• Some diagrams, particularly sequence diagrams, work better when placed on a page with landscape orientation.
• When drawing inheritance structures follow the common formatting of having the super-class above the sub-classes, grouping all sub-classes together, and using a common inheritance line for all sub-classes.
• Your documentation should have numbered headings for sections.
• Page numbers add the last little touch of professionalism to your documentation.

$Id: TypicalAreasForImprovement.html 206 2010-03-15 03:31:32Z jrv $