Re: Documenting Individual Objects

[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)]

In article <D2150022.v8eon3@ron.bse.com> 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 -           *