What Does a Java Design Specification Look Like?

A secification for a software system to be developed in Java may contain some or all of the following. Depending on the complexity and requirements of the system, some aspects will be more important than others; I am assuming that use cases or requirements, or a features list (or all of these) have already been documented. A detailed design will address all of the following areas, except those that are not applicable to the system; a logical design will address fewer areas. By having matching sections, it is possible to map the changes from a logical design to a detailed design. A detailed design document should also explain decisions that were made that led to differences between the logical and detailed design. (Recall that differences between a logical and detailed design do not necessarily represent inconsistency; the physical model need not have the same objects as the logical model.)

  • Design Description: An overview of the design, explaining how components interact and the primary logical flow. Recommended format: informal.
  • Object model: An object model, which identifies interfaces, classes, and their cardinalities, and identifies the composite objects that will form the basis of transactions. In a logical design, it would be advisable to postpone the specification of concrete classes and leave classes abstract. Recommended format: UML class diagrams.
  • Member specification: An exact specification (well commented interfaces and classes) of the methods, attributes, and associations in each of the interfaces and classes, and the purpose of each. Ultimately, you want to express these in Java so that these specifications can be incorporated into the code. Consider using “javadoc” code commenting conventions, and embedding diagrams via HTML tags. An alternative, however, is to fully annotate the object model and generate these specifications automatically, using a tool such as Rational Rose or Together Java. The challenge is that the specifications are likely to be many paragraphs if not more per method, and the tool must accommodate this. For methods, these specifications should say what the methods do, and optionally how; see Functional specification below.
  • Environment specification: A specification of the planned deployment environment(s), and the approximate expected usage pattern, volume, and other characteristics don't leave scalability considerations for a later phase. Format: text, UML implementation diagrams, use case diagrams, tables, and charts.
  • Design concepts: Decisions about key issues, such as transactional behavior. (See the chapter on databases.) Format: informal text and diagrams, UML collaboration or sequence diagrams, activity or statechart diagrams, and class diagrams.
  • Functional specification: Pseudocode or scenarios for key behavior. This can be incorporated into the member specification if desired. If the application contains visual components, their layouts and designs should be specified in this section. Applicable formats: UML collaboration or sequence diagrams, Java pseudocode, activity or statechart diagrams, and screen shots. If the system requirements include a features list, all items in it should be referenced by the functional specification.
  • Package specification: What the packages will be (the major ones); and a description of the purpose of each package, which packages are reusable, which packages are independently deployable, and the primary dependencies between the packages. Format: text, Java, and UML package diagrams.
  • External interfaces identification: Any other schemas or components that may be required to interact with external systems. Format: text, IDL, tables, and diagrams appropriate for the external systems, class diagram for the interfacing components in this system; collaboration, sequence, activity, or statechart diagrams; UML implementation diagram.
  • Exception specification: Primary kinds of exceptions, and strategies for generating and handling exceptions. This should be a text document, with class diagram, which identifies the base Java exception classes (modeled as a “signal” in UML see below), from which all project exception classes will derive. It also specifies what information will be encoded in exception messages, and criteria for deciding at what levels of code exceptions should be handled, propagated, or converted.
  • Resource specification: Primary categories of properties, messages, resources, and basic components and strategies for accessing and managing them. This is a textual specification; an exact specification of resource adapter classes, if any, is provided in other applicable sections as for any other system component, and may be referenced.
  • Naming specification: Naming conventions to be followed for all named elements in the implementation. You can fold this specification into the sections above that apply to each type of named element, keep it separate, or place it in a coding style guide (see below). It is a good idea to follow and extrapolate from the naming conventions in the JavaBeans specification. (See the JavaBeans chapter.)
  • Coding style guide: Aesthetic guidelines for the implementation code and scripts.
  • Test specification: A set of tests to be performed and test systems to be constructed. Format: text, or a test-tool-specific format.
  • Deployment specification: A specification of the tools required, means, and manner in which the system is to be put into initial operation. This is not to be confused with the environment specification, which defines the operational environment; in contrast, this specification defines the system and procedures for installing and bringing the system into operation. Format: text, UML implementation diagram, and other charts and diagrams as appropriate. A question that arises is, can Java be used as a modeling or domain specification language? And, if so, should analysts learn Java? My own feeling about this is mixed. Java is a low level language, but it is objects oriented. It is not productive for domain experts to spend time learning how to code Java statements. However, it is useful for analysts on a Java project to understand the specifics of Java's objects oriented features, such as classes and interfaces. Having a concrete understanding of these helps enormously when dealing with UML abstractions. It also facilitates communication between developers and analysts.

Extract from "Advanced Java Development for Enterprise Application" written by Clifford J. Berg Published by Prentice Hall PTR New Jersey 1998