🚀 go-pugleaf

Don Joslyn writes:

> I would be grateful for  any suggestions on the  documentation
> of objects.  Thanks in advance for your feedback.

One of the most common forms of documentation in an object-oriented
system is the "object and class specification," or OCS (pronounced
"ox" -- some pronounce the plural "oxen"). OCSs are most commonly used
to document classes, although in a language which allows anonymous
classes, e.g., Ada, they can be used to document individual instances
of anonymous classes.

A complete discussion of the design, contents, and software quality
assurance for an OCS would take up much more room than I care to use
in this short message, but here are the highlights.

An OCS has five parts:

	- the Precise and Concise Description: One could say that this
	  is an "executive summary" for the object or class. The
	  required contents of this section are well-defined, and may
	  be textual, graphical, or otherwise.

	- the Graphical Representations: The three main graphical
	  representations used in an OCS are: semantic networks (to
	  show static relationships), state transition diagrams (to
	  show dynamic behavior of the individual object or class),
	  and Petri net graphs (to show dynamic behavior involving two
	  or more objects of the same class)

	- the Suffered and Required Operations: Both operations (the
	  capabilities "advertised" (or "exported") in the interface
	  to the object or class) and methods (the internal
	  implementations of the operations, i.e., the algorithms)
	  must be shown. However, methods are only discussed at a
	  level of abstraction appropriate to a user of the object or
	  class, e.g., "what does this operation do?"

	  Suffered operations are those operations "advertised"
	  ("exported") by the object or class. Required operations are
	  those operations "imported" by the object or class so that
	  it may accomplish some, or all, of its suffered operations
	  without "object coupling."

	- the State Information: When we say that two objects are
	  "equal" what we are really saying is that their states are
	  equal. To truly understand a class, we must understand the
	  states which its instances can assume. This is especially
	  important in the case of an "object with life," i.e., an
	  object which can spontaneously change its own state.

	- the Constants and Exceptions: Objects and classes can export
	  more than just operations. They can provide their users with
	  useful constants and exceptions.

Other useful information about OCSs:

	- They are programming language independent. I have taught
	  classes where the attendees used many different programming
	  languages, but they all could use the same OCS.

	- They can be used to describe items other than code software.
	  An OCS is appropriate for (and has been used for) describing
	  such items as hardware, humans (e.g., operators and members
	  of an organization), and non-code software.

	- They are highly reusable. If constructed properly, and
	  quality assured, an OCS can be reused on different projects,
	  and even by different organizations.

	- They can be created, used, and reused in several different
	  software engineering processes, e.g., object-oriented domain
	  analysis (OODA), object-oriented requirements analysis
	  (OORA), and object-oriented design (OOD).

As useful as OCSs are, they are not the only type of object-oriented
documentation necessary. During object-oriented development in the
large (OODIL), one encounters "subsystem descriptions," "systems of
objects descriptions," and various object-oriented life-cycle process
documents (e.g., the object-oriented requirements specification
(OORS)).

				-- Ed Berard
				   Berard Software Engineering, Inc.
				   18620 Mateney Road
				   Germantown, Maryland 20874
				   Phone: (301) 353-9652