don@dons3b1.UUCP (Don Joslyn) (06/04/89)
Hi,
I'm a "C" programmer who is now considering using an
Object-Oriented programming language. Since a "function" is
different than an "object", then maybe the documentation should
also be different. I've seen many standards proposed for the
documentation of functions, and I am now interrested in finding
ideas for documentation of objects. What additional documentation
is required for an object? Do you know of a standard, use a
standard, or have ideas or pointers to articles for documentation
of objects?
I would be grateful for any suggestions on the documentation
of objects. Thanks in advance for your feedback.
--
Don Joslyn
Cooper City, Florida
UUCP: ...{gatech!uflorida,ucf-cs}!novavax!dons3b1!doneberard@ajpo.sei.cmu.edu (Edward Berard) (06/05/89)
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
cassel@sce.carleton.ca (Ron Casselman) (06/06/89)
In article <23@dons3b1.UUCP> don@dons3b1.UUCP (Don Joslyn) writes: > > I would be grateful for any suggestions on the documentation > of objects. Thanks in advance for your feedback. > >-- >Don Joslyn >Cooper City, Florida >UUCP: ...{gatech!uflorida,ucf-cs}!novavax!dons3b1!don Try "Object Oriented Programming An Evolutionary Approach" by Brad J. Cox. The author draws an analogy between hardware specification sheets and documentation sheets for objects. Object documentation should be precise and concise so that experienced programmers can find information quickly. The author suggests an object documentation layout and uses it to document the object classes provided with the Objective C compiler from StepStone Corporation. I find inheritance graphs invaluable aids as well. Ron Casselman Systems Engineering, Carleton University Ottawa Canada
jima@hplsla.HP.COM (Jim Adcock) (06/10/89)
Try writing a un*x manual page for it. If that doesn't seem to fit the bill, its probably not an object.