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=-0.5 required=3.0 tests=BAYES_05 autolearn=ham autolearn_force=no version=3.4.5-pre1 Date: 23 Apr 93 16:26:29 GMT From: ulowell!swlvx2!rayssd!galaxia!zoe!terry@uunet.uu.net (Terry) Subject: Re: Documenting Individual Objects Message-ID: <1993Apr23.162629.8897@zoe.network23.com> List-Id: >>From article , by henley@eng. auburn.edu (James Paul Henley): > In article 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