Documenting Individual Objects 
Author Message
 Documenting Individual Objects

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. Brad Cox in his OOP: an Evolutionary
Approach discusses and illustrates a text based approach to object
specification. Ed Berard in his Essays on Object-Oriented Software
Engineering details an object and class specification that extends
Cox's approach with the addition of static and dynamic graphics. Coad
and Yourdon also show an object and class specification, but only Berard
provides enough examples to demonstrate that the technique is somewhat
flexible. Does anyone know of other specification techniques for documenting
objects independent of some particular application? Any references
or comments would be appreciated.

----------------------------------------------------------------------------
Ronald C. Schultz                               | Phone: (301) 417-9884
Berard Software Engineering, Inc.               | FAX:   (301) 417-0021

Gaithersburg, Maryland 20877                    |
----------------------------------------------------------------------------



Tue, 03 Oct 1995 18:29:44 GMT  
 Documenting Individual Objects

Quote:
>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.

Quote:
> 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



Sun, 08 Oct 1995 01:08:52 GMT  
 Documenting Individual Objects
   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.



Mon, 09 Oct 1995 01:38:10 GMT  
 Documenting Individual Objects

Quote:

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

Data is not information is not knowledge is not wisdom.



Mon, 09 Oct 1995 06:20:01 GMT  
 Documenting Individual Objects

Quote:


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

>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



Mon, 09 Oct 1995 20:41:36 GMT  
 Documenting Individual Objects

Quote:
>  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                                             |



|                                                                  |
|          Phone: (717) 941-7446         FAX:   (717) 941-4250     |
+------------------------------------------------------------------+



Tue, 10 Oct 1995 03:20:50 GMT  
 Documenting Individual Objects

Quote:


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

Quote:

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

Quote:

> Dr. James P. Henley Jr.

Terry
--

{rayssd,xanth,mirror,att}!galaxia!zoe!terry


Wed, 11 Oct 1995 00:26:29 GMT  
 Documenting Individual Objects

Quote:


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

 ...

Quote:
> 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




Wed, 11 Oct 1995 10:59:48 GMT  
 Documenting Individual Objects

Quote:

>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



Fri, 13 Oct 1995 21:32:22 GMT  
 Documenting Individual Objects

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

* Bang {uupsi,uunet}!bony1!richieb |      I'm doing basic research."          *
*    - Strictly my opinions -      |          - Wernher von Braun -           *



Sat, 14 Oct 1995 21:03:47 GMT  
 
 [ 10 post ] 

 Relevant Pages 

1. Documenting Individual Objects

2. Icons for Individuals Objects

3. DOM, Document Object Model

4. Using the XML Document Object Model

5. Documenting an Object Oriented Design

6. Reading and saving data of VRML objects in XML document

7. Global Document Handling Template - Document Send Extension

8. document, document

9. How to count the number of individual strings?

10. individual characteristics of a compuer

11. Individuals that know Smalltalk in Missouri

12. STIC Individual memberships

 

 
Powered by phpBB® Forum Software