Re: Documenting Individual Objects

Re: Documenting Individual Objects

[Ralph Johnson]

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.

The reason for this is that (in my opinion) documenting a single
class is easy, and is similar to traditional function-oriented
documentation, but documenting object-interactions is much harder.
For example, in Smalltalk I am perfectly happy with class comments
and method comments as documentation for a class, but they fall apart
as documentation for how objects work together.

> d) has sufficient internal
>consistency checks and heuristics to allow me to determine if the object
>is complete, consistent, and usable. 

I don't believe that this can be done just from the documentation.

-Ralph Johnson

Re: Documenting Individual Objects

[cis.ohio-state.edu!zaphod.mps.ohio-state.edu!usc!news.bbn.com!ulowell!swl]

   The methodology outlined in "Object-Oriented Modeling and Design" by
Rumbaugh et al is a good example of a more robust methodology.  There seems
to be a good balance between:
	Object interaction and Individual object behaviour
	System composition vs. system behavior

   MHO for what it's worth.

Re: Documenting Individual Objects

[cis.ohio-state.edu!zaphod.mps.ohio-state.edu!howland.reston.ans.net!bogus]

johnson@cs.uiuc.edu (Ralph Johnson) writes:

>> ...
>The reason for this is that (in my opinion) documenting a single
>class is easy, and is similar to traditional function-oriented
>documentation, but documenting object-interactions is much harder.
>For example, in Smalltalk I am perfectly happy with class comments
>and method comments as documentation for a class, but they fall apart
>as documentation for how objects work together.

Perhaps you should be able to specify when and how objects interact?
Then you wouldn't need to document... the code would serve.

-- 

Lance Norskog
thinman@netcom.com
Data is not information is not knowledge is not wisdom.

Re: Documenting Individual Objects

[howland.reston.ans.net!bogus.sura.net!darwin.sura.net!news.duc.auburn.edu]

In article <thinmanC5uu1E.Hyo@netcom.com> thinman@netcom.com (Technically Sweet
) writes:
>johnson@cs.uiuc.edu (Ralph Johnson) writes:
>
>>> ...
>>The reason for this is that (in my opinion) documenting a single
>>class is easy, and is similar to traditional function-oriented
>>documentation, but documenting object-interactions is much harder.
>>For example, in Smalltalk I am perfectly happy with class comments
>>and method comments as documentation for a class, but they fall apart
>>as documentation for how objects work together.
>
>Perhaps you should be able to specify when and how objects interact?
>Then you wouldn't need to document... the code would serve.
>
>-- 
>
>Lance Norskog
>thinman@netcom.com
>Data is not information is not knowledge is not wisdom.

I hate to mention the obvious, but...

In a dynamic chemical process simulation using OO methods, I doubt if there
are many non-chemical engineers who could describe the object interations.
The object interactions is the heart of the simulation, but that requires
domain specific knowledge to understand.    As far as the interface between
the objects goes, that is simply a matter of knowing what type of information
is passed from object to object, and that is easy to document.  But,
understanding how the objects work together means you have to understand
chemical processes!

So, it requires a domain expert to document how the objects work together.
That is the point that gets lost all too often, but is the key factor in
making OO successful.

Dr. James P. Henley Jr.
Department of Chemical Engineering
Auburn University

Re: Documenting Individual Objects

[cis.ohio-state.edu!pacific.mps.ohio-state.edu!zaphod.mps.ohio-state.edu!u]

In article <1r3ngeINN4mv@umbc7.umbc.edu> Mr. Kenneth Rowe writes
     
>  Has anyone taken a stab at including Ada9X features into their current
>  Ada courses?  Does "introducing Ada9X" look like it will be helpful?
>       
>  Ken. 
>  

I'm ready to role as soon as someone out there is willing to play
"let's make a deal" and let me try out a beta test 9X compiler.  I
have Janus' beta test 9X for PCs and am using it to rework my Ada
tools and data structure components to give them an "object-oriented"
flavor using 9X.  If I can get a decent beta version of 9X this summer,
I plan to use 9X in my Advanced Data Structures Course this fall.
If I can get one by Christmas, I plan to use 9X in my CS 2 course in
the spring.

I will only use 9X if I have it.  I don't like giving students
demonstrations pieces of code (in 9X), if they don't have the resources
to play with it.

I feel that CS 2 and the Advanced Data Structures courses are two
courses that are primed for Ada-9X and a stronger OO flavor.  I
might add that I recently reviewed a CS 1 text with an OO flavor
that really impressed me.  The book was good, but it used a non-
standard corruption of Pascal -- the book would be great if done
in 9X.

So you compiler guys out there -- if you want to get lots of people
checking out you compiler, we got lots of eager students who are
ready to give it a work out.
-- 
+------------------------------------------------------------------+
|  John (Jack) Beidler				                   |
|  Prof. of Computer Science Internet: BEIDLER@JAGUAR.UOFS.EDU     |
|  University of Scranton              beidler@guinness.cs.uofs.edu|
|  Scranton, PA 18510	      Bitnet : BEIDLER@SCRANTON            |
|                                                                  |
|          Phone: (717) 941-7446	 FAX:   (717) 941-4250     |
+------------------------------------------------------------------+

Re: Documenting Individual Objects

[Terry]

>From article <henley.930422074136@einstein.che.eng.auburn.edu>, by henley@eng.
auburn.edu (James Paul Henley):
> In article <thinmanC5uu1E.Hyo@netcom.com> thinman@netcom.com (Technically Swe
et) writes:
>>johnson@cs.uiuc.edu (Ralph Johnson) writes:
>>
>>>> ...
>>>The reason for this is that (in my opinion) documenting a single
>>>class is easy, and is similar to traditional function-oriented
>>>documentation, but documenting object-interactions is much harder.
>>>For example, in Smalltalk I am perfectly happy with class comments
>>>and method comments as documentation for a class, but they fall apart
>>>as documentation for how objects work together.
>>
>>Perhaps you should be able to specify when and how objects interact?
>>Then you wouldn't need to document... the code would serve.
>>
>>Lance Norskog
> 
> I hate to mention the obvious, but...

What is obvious depends on your perspective.

> 
> In a dynamic chemical process simulation using OO methods, I doubt if there
> are many non-chemical engineers who could describe the object interations.
> The object interactions is the heart of the simulation, but that requires
> domain specific knowledge to understand.    As far as the interface between
> the objects goes, that is simply a matter of knowing what type of information
> is passed from object to object, and that is easy to document.  But,
> understanding how the objects work together means you have to understand
> chemical processes!
> 
> So, it requires a domain expert to document how the objects work together.
> That is the point that gets lost all too often, but is the key factor in
> making OO successful.

Your perspective is OO modeling of chemical processes, but many of us reading
these newsgroups are software developers so our perspective is application
development.  The problem I have seen with current documentation methods is
that it difficult to know what state changes will occur as a result of a
message send.  This is very important when developing a complex application.
Such applications frequently are decomposed as cooperating agents.  The
problem is when a method of one object may send a message to a cooperating
agent which results in another message eventually being sent back to the
original object and changing its state.  The programmer who wrote the original
message may be unaware of the complex relationship and therefore the state
change results in the object being in an unanticipated state and eventually
causing a software error.  While it may be easy to say that this occurred
as a result of poor design, when one examines each method in a local context
they appear ok.  Whats really needed is to examine them in a global context.
This is the same as the tradeoff between local and global optimization.
The object-oriented paradigm aids the designer in decomposing a problem by
reducing the complexity of the problem into a description of several smaller,
but local, descriptions.  What we need is a tool to recompose the global
description from the local descriptions so the global interactions can be
brought to our attention.  Sort of looking at the forest instead of the trees.

> 
> Dr. James P. Henley Jr.

Terry
-- 
terry@zoe.network23.com
{rayssd,xanth,mirror,att}!galaxia!zoe!terry

Re: Documenting Individual Objects

[mole-end!mat]

In article <henley.930422074136@einstein.che.eng.auburn.edu>, henley@eng.auburn
.edu (James Paul Henley) writes:
> In article <thinmanC5uu1E.Hyo@netcom.com> thinman@netcom.com (Technically Swe
et) writes:
> >johnson@cs.uiuc.edu (Ralph Johnson) writes:

> >>The reason for this is that (in my opinion) documenting a single
> >>class is easy, and is similar to traditional function-oriented
> >>documentation, but documenting object-interactions is much harder.
 ...
> >Perhaps you should be able to specify when and how objects interact?
> >Then you wouldn't need to document... the code would serve.

 ...
> In a dynamic chemical process simulation using OO methods, I doubt if there
> are many non-chemical engineers who could describe the object interations.
> The object interactions is the heart of the simulation, but that requires
> domain specific knowledge to understand.  ...
 
> So, it requires a domain expert to document how the objects work together.
> That is the point that gets lost all too often, but is the key factor in
> making OO successful.

Which is why most of the interesting OO examples are taken from computing
problems (including human-machine interface).
-- 
 (This man's opinions are his own.)
 From mole-end				Mark Terribile

 mat@mole-end.matawan.nj.us, Somewhere in Matawan, NJ

Re: Documenting Individual Objects

[agate!howland.reston.ans.net!zaphod.mps.ohio-state.edu!darwin.sura.net!ne]

In article <1993Apr23.162629.8897@zoe.network23.com> terry@zoe.network23.com (T
erry) writes:
>
>development.  The problem I have seen with current documentation methods is
>that it difficult to know what state changes will occur as a result of a
>message send.  This is very important when developing a complex application.
>Such applications frequently are decomposed as cooperating agents.  The
>problem is when a method of one object may send a message to a cooperating
>agent which results in another message eventually being sent back to the
>original object and changing its state.  The programmer who wrote the original
>message may be unaware of the complex relationship and therefore the state
>change results in the object being in an unanticipated state and eventually
>causing a software error.  While it may be easy to say that this occurred
>as a result of poor design, when one examines each method in a local context
>they appear ok.  Whats really needed is to examine them in a global context.
>This is the same as the tradeoff between local and global optimization.
>The object-oriented paradigm aids the designer in decomposing a problem by
>reducing the complexity of the problem into a description of several smaller,
>but local, descriptions.  What we need is a tool to recompose the global
>description from the local descriptions so the global interactions can be
>brought to our attention.  Sort of looking at the forest instead of the trees.
>

Believe it or not, you just summed up how I intend to use OO for Chemical
Process Modeling.  I need a tool to decompose a process into cooperating
agents, which we would call "Unit Operations".  Then I need to take it
one step further and decompose those into "Stages".  Each stage is fairly
simple to describe, at least compared to the process as a whole.  Then those
stages need to send messages back and forth, and the unit operations need
to send messages back and forth, and the result of this exchange of 
information is highly complex, with the state of every single stage being
affected by the complex relationships.

I am counting on the complexity of the interactions between software objects
to be analogous to the complexity of the interactions between real objects.
The interactions in a chemical process are continuous, and so you have to
correct for the fact that you are using a model that is based on discrete
events.

Really what I am doing is the same in principle as analog computers, which
are still used in the chemical industry.  You can build an electrical circuit
that is analogous to a simiplified chemical process, and then use the
same analysis techniques, such as Laplace transforms, and transfer functions.
The problem is that to model a real world process accurately, you have all
sorts of non-continuous perturbations that transfer functions simply can't
handle.  And when you try to model highly non-linear, *very* complex systems,
such as real world chemical processes tend to be, the anaysis using
transfer functions gets out of hand in a hurry.

Surely some of your "applications" have applications outside of Computer
Science, don't they?  I can see where an accounting application, for 
example, would have complexities that only an accountant would fully
understand.  While I was in grad school, I moonlighted as a programmer,
and I customized an accounting package written in FoxBase for SCO Xenix.
Although I completely understood how the information got from place to 
place, and how the calculations were performed, I still did not understand
how any one particular transaction affected the overall picture as well
as the plant comptroller did.   And all those blasted paper trails drove
me crazy, but then I never had to face the auditors...

Dr. James P. Henley Jr.
Department of Chemical Engineering
Auburn University

Re: Documenting Individual Objects

[agate!howland.reston.ans.net!usc!cs.utexas.edu!utnut!torn!nott!bnrgate!bn]

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 -           *