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.1 required=5.0 tests=BAYES_05,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: Robert Bernecky Subject: Re: Documenting Code (was:Programming language vote - results) Date: 1997/10/31 Message-ID: <3459F9D5.4DA84B41@acm.org>#1/1 X-Deja-AN: 286198713 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> <63au56$hol$1@walter.cs.umd.edu> To: Charles Lin X-Complaints-To: usenet@news1.tor.acc.ca X-Trace: news1.tor.acc.ca 878311635 29581 (None) 142.154.22.199 Organization: ACC TelEnterprises Ltd. Newsgroups: comp.lang.ada,comp.lang.apl,comp.lang.c,comp.lang.c++ Date: 1997-10-31T00:00:00+00:00 List-Id: Charles Lin wrote: > 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. Indeed. Consider the usual situation: You get hired into a project with these characteristics: - anyone who designed the original system has been laid off or has gone to greener pastures. - the system has been maintained for the last 3 years by apprentice programmers whose previous job was mechanic in a muffler shop. - part X of the system is chewing entire mainframes and growing at 15% per month. The documentation you want to see (and rarely ever do) is: - What is the INTENT of part X? E.g., in a matrix inversion routine, you want something of the form: "This function solves sparse linear systems. We don't use the built-in DOMINO primitive to do this, because the arrays have 250,000 rows and domino doesn't know from sparseness today." - What is going to break if I change/replace/rewrite this? In APL, this is a pain to determine, because of APL's prehistoric dynamic scoping rules. You have to know everyone who calls you (if you use/set a variable that's global to you), and you have to know everyone you call (if you set or use any variable), because ALL of your variables are visible to everyone you call. My approach lately has been to feed the entire application into the APEX APL compiler, which determines this as part of the setup for a later data flow analysis phase. In a large system, it's hard because you end up with . Black-box subapplications that (for historical reasons of wee, tiny main memories) set global/semi-global variables. No, you do not have access to the source code for the black box. . huge function paging files that are either unavailable or undecypherable. The advent of code maintenance systems such as LOGOS help the latter, but not the former. Bob