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
