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.7 required=5.0 tests=BAYES_00,INVALID_DATE, MSGID_SHORT,REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4 Xref: utzoo comp.software-eng:1252 comp.lang.ada:2163 Path: utzoo!utgpu!utstat!jarvis.csri.toronto.edu!mailrus!nrl-cmf!ames!ll-xn!mit-eddie!uw-beaver!tektronix!pogo!rickc From: rickc@pogo.GPID.TEK.COM (Rick Clements) Newsgroups: comp.software-eng,comp.lang.ada Subject: Re: comments on comments on comments Message-ID: <6901@pogo.GPID.TEK.COM> Date: 9 Mar 89 21:12:24 GMT References: <419@serene.UUCP> <4534@hubcap.UUCP> Reply-To: rickc@pogo.GPID.TEK.COM (Rick Clements) Organization: Tektronix, Inc., Wilsonville, OR. List-Id: In article <2989@uvacs.cs.Virginia.EDU> you write: >In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes: >>What is needed to improve self-documentation are better programming languages. >This is certainly true, but even the "better" programming languages allow for >the inclusion of comments. There will probably always be parts of the >programmer's concept which need to be expressed in an informal way through >comments. I have learned to include comments like "Doing it appeared obvious at first but didn't work because of ". I hate solving the same problem twice (even if it a year or so later). You can also list what trade offs lead you to solve a problem the way you did. The code can never tell you the why. Telling the person maintaining the code (maybe yourself) why something was done will help them from creating those crash every 5th Tuesday type of bugs. ---- Rick Clements (RickC@pogo.WV.TEK.COM) -- Rick Clements (RickC@pogo.WV.TEK.COM)