From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.5-pre1 (2020-06-20) on ip-172-31-74-118.ec2.internal X-Spam-Level: X-Spam-Status: No, score=-1.9 required=3.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.5-pre1 Date: 27 Apr 93 13:03:47 GMT From: agate!howland.reston.ans.net!usc!cs.utexas.edu!utnut!torn!nott!bnrgate!bn r.co.uk!uknet!pipex!sunic!psinntp!psinntp!bony1!richieb@ucbvax.Berkeley.EDU (R ichard Bielak) Subject: Re: Documenting Individual Objects Message-ID: List-Id: In article ron@bse.com (Ronald C. Schultz) writes : >I am interested in tools and techniques individuals and organizations >are using to document objects. There appears to be few, well-thought >out and complete methods to articulate objects. Many of the existing >methods (e.g., OMT, Wirfs-Brock, ...) concentrate on documenting >object-interactions, but not on documenting the objects themselves. >In point of fact I have been relatively frustrated in trying to identify >a documentation technique that a) is straightforward to use, b) can >be applied consistently, c) is indexable to allow for future incorporation >into an in-house reusablility library, and d) has sufficient internal >consistency checks and heuristics to allow me to determine if the object >is complete, consistent, and usable. [...] First of all should the subject be "Documenting Classes"? :-) Anyway, I'm suprized that no one in this thread mentioned Eiffel and the "short" and "flat" tools. As you know, in an Eiffel class each routine can have pre- and postconditions, which can describe when a routine can be called and what it will accomplish. In addition each class can have invariants, which are assertions that must be true all the time in all instances (not entirely true, invariants can become false while object's routine is executing). The "short" tool extracts the visible interface from an Eiffel class, including the pre- and postconditions, and the invariant. The "flat" tool flattens the inheritance hierachy. Typically to see the entire interface to a class you apply "flat" followed by "short". In addition to correctness checking, the assertion provide great documentations for the users of the class. For example, here is an extract from a "short" listing of POBJECT (persistet object) class: class interface POBJECT exported features [...stuff deleted here...] feature specification is_persistent: BOOLEAN make_persistent require not_persistent: not is_persistent; ensure persistent: is_persistent; locked: current_lock.value = write_lock delete require object_persistent: is_persistent; locked: current_lock.value = write_lock ensure not is_persistent current_lock: expanded OBJECT_LOCK -- Lock on this object [...stuff omitted...] end interface -- class POBJECT Take a look at the "make_persistent" routine. The assertions say that to make the object persistent, it must not already be persistent and after we're done, it will be persistent and *also* it will be write locked. This is the kind of information programmers need. Another advantage of assertions is that they are part of the code, so they will have to be modified when the code is changed. How often do you update documentation after fixing old code? :-) ...richie -- * Richie Bielak (212)-815-3072 | * * Internet: richieb@bony.com | "When I don't know what I'm doing, * * Bang {uupsi,uunet}!bony1!richieb | I'm doing basic research." * * - Strictly my opinions - | - Wernher von Braun - *