From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=BAYES_00,INVALID_DATE, MSGID_SHORT autolearn=no autolearn_force=no version=3.4.4 Xref: utzoo comp.software-eng:1046 comp.lang.misc:2679 comp.lang.ada:1975 Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!ucbvax!decwrl!purdue!rjh From: rjh@cs.purdue.EDU (Bob Hathaway) Newsgroups: comp.software-eng,comp.lang.misc,comp.lang.ada Subject: Re: comments on comments Message-ID: <6010@medusa.cs.purdue.edu> Date: 10 Feb 89 21:16:33 GMT References: <1813@goofy.megatest.UUCP> Sender: news@cs.purdue.EDU Organization: Department of Computer Science, Purdue University List-Id: Dave Jones [djones@megatest.UUCP] Writes: >Here are some remarks that I wrote up for one of the >members of my programming team. I hope they will be >helpful. Thanks, I agree good documentation is invaluable. > >In my opinion, the most important parts of a program to document >are the structure-declarations and the variable-declarations. > This is true, but alternate design strategies can call for an extended perspective on documentation. When using an object oriented design strategy, I'll first write a design document describing the primary objects in the system and their operations. Also in the document will be a high-level description of the important procedures written in an informal PDL, such as a pseudo Ada code. For objects (Adts), first is a description of the object and its rational and system context. For instance, what the object is intended for, why I chose an abstract data object or an abstract data type, and possibly how it will interact in the system, but the last part could go in a separate document as pointed out by Dave Jones. Second is a numbered list of operations and their descriptions. When the entire system is complete, the declarations can be coded in a higher-order language. In Ada, the design is directly implementable as compilable specifications. In Modula or some other language in which the specifications aren't compilable the procedures can be filled in with stubs or empty declarations. The design document can be included as comments and updates to the document and code should be done concurrently. The object descriptions are included in the specifications and optionally in the package or module body, and the (numbered) operation descriptions included for each procedure or method. >Here's a good way to go about it: > >/******************************* > * This is one block comment, > * and it is easy to modify. > ******************************/ > Here's another way: /* * my_procedure * * * This is a description of... * ... */ Bob Hathaway rjh@purdue.edu