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=-1.3 required=5.0 tests=BAYES_00,INVALID_MSGID
	autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 11390f,4c42ac518eba0bbe
X-Google-Attributes: gid11390f,public
X-Google-Thread: 1014db,4c42ac518eba0bbe
X-Google-Attributes: gid1014db,public
X-Google-Thread: 109fba,4c42ac518eba0bbe
X-Google-Attributes: gid109fba,public
X-Google-Thread: 103376,4c42ac518eba0bbe
X-Google-Attributes: gid103376,public
From: clin@cs.umd.edu (Charles Lin)
Subject: Re: Documenting Code (was:Programming language vote - results)
Date: 1997/10/30
Message-ID: <63au56$hol$1@walter.cs.umd.edu>#1/1
X-Deja-AN: 286026310
References: <343fbb5a.0@news.iprolink.ch> <343FD05C.8986A557@flash.net>
 <34428914.2D71D0F@ibm.net> <01bcd87f$7fefcf00$25a43a91@basil.omroep.nl>
 <34458CE3.507C@dynamite.com.au> <3444BFC6.794BDF32@druid.net>
 <34466EB4.3381@dynamite.com.au> <6275dt$agm$3@news.on>
 <344BCED0.2D51@dynamite.com.au> <62idmb$htg$1@news.on>
 <344DEAA9.5115@hal-pc.org> <01bce1bf$5c2baaa0$95b66bcf@dkelly.ark.com>
 <345776DD.424B@hal-pc.org> <3459A84A.246@dynamite.com.au>
Followup-To: comp.lang.ada,comp.lang.apl,comp.lang.c,comp.lang.c++
Organization: U of Maryland, Dept. of Computer Science, Coll. Pk., MD 20742
Newsgroups: comp.lang.ada,comp.lang.apl,comp.lang.c,comp.lang.c++
Date: 1997-10-30T00:00:00+00:00
List-Id: <comp.lang.ada>


    One problem with documenting code is that it is often at too fine
a level.   That is, you document individual functions or classes, when
what the user really wants is the overall structure of the code, as
well as how this solution solves the problem.   Sometimes, one practically
wants an overview manual of the code, including the approach to the
solution, the data structures used, and their interactions.

    So, you might have a, say, CAD tool.   You might have objects
that stand for shapes (rectangles, circles), objects that stand
for treating sevearal base objects as a whole.   Objects to keep
track of the state of what is being done (draw, insert, delete,
copy, etc).    Most people would simply comment each of the classes,
but this still gives only a vague idea of how it all fits together.

    I think that producing such a general document might also be
useful for implementors, forcing them to put into words, ideas they
have in their head.   This is esp. important for people who write
code for themselves (or in classes).   By placing idea to paper,
they may clarify muddy thoughts which lead to muddy designs.

--
Charles Lin
clin@cs.umd.edu