Xref: utzoo comp.software-eng:2598 comp.misc:7561
Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!cs.utexas.edu!usc!snorkelwacker!bloom-beacon!athena.mit.edu!tada
From: tada@athena.mit.edu (Michael J Zehr)
Newsgroups: comp.software-eng,comp.misc
Subject: Re: Coding standards (was Re: Programmer productivity)
Summary: self-documenting
Message-ID: <1989Dec4.222725.5920@athena.mit.edu>
Date: 4 Dec 89 22:27:25 GMT
References: <Nov.18.22.47.26.1989.9685@paul.rutgers.edu> <34796@regenmeister.uucp> <2226@jato.Jpl.Nasa.Gov> <128179@sun.Eng.Sun.COM> <546@sagpd1.UUCP> <4727@netcom.UUCP> <9157@hoptoad.uucp> <473ae701.20b6d@apollo.HP.COM>
Sender: root@athena.mit.edu (Wizard A. Root)
Reply-To: tada@athena.mit.edu (Michael J Zehr)
Organization: Massachusetts Institute of Technology
Lines: 34

In article <473ae701.20b6d@apollo.HP.COM> perry@apollo.HP.COM (Jim Perry) writes:
>There's not much time overhead in generating [heirarchical 
>documentation], assuming a
>basic competence at technical writing to one's own level.  At design time
>most of this information is probably either already written down or on the
>forefront of the programmer's brain (I often design code by writing the 
>documentation).  This sort of information *can't* easily be reconstructed
>from reading C code.  ("now WHY was I cocky enough to code this loop
>without explicitly guarding against interrupts?")  
>-
>Jim Perry   perry@apollo.com    HP/Apollo, Chelmsford MA

I heartily agree with this, but unfortunately i rarely see it in
practice.  The largest project i ever did entirely by myself (a library
of calls to handle a user interface, including things like 'make button'
and 'call this function when the user clicks this region', etc.)
amounted to around 2000 lines of C code.  After designing it, I started
the coding by writing 3-5 lines describing each function.  When i went
to write the actual code, i was able to do it all very quickly, and
those 3-5 lines of description for each function have saved enormous
time and effort enhancing the library.

On top of that, I don't think it took any extra time to write, even to
start with.  I was basically sitting at the terminal thinking "how do i
start this" and decided typing what i knew was the best way to start.  I
think the time to write the comments plus the time to write the code was
less than if i had just started in on the code.  

Unfortunately, i've gotten a lot of comments along the lines of "i'm too
busy writing code to write a comment describing it" when suggesting it
to others.  I guess keeping maintenance costs high is what keeps some
people in business... :-\ 

-michael j zehr


Brought to you by Super Global Mega Corp .com