Re: Documenting Individual Objects

[howland.reston.ans.net!bogus.sura.net!darwin.sura.net!news.duc.auburn.edu !eng.auburn.edu!henley@gatech.edu (James Paul Henley)]

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