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.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,fc52c633190162e0 X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news1.google.com!news4.google.com!news.glorb.com!news.ecp.fr!news.jacob-sparre.dk!pnx.dk!not-for-mail From: "Randy Brukardt" Newsgroups: comp.lang.ada Subject: Re: commenting, was Re: Use of declare blocks Date: Fri, 23 Mar 2007 22:19:21 -0500 Organization: Jacob's private Usenet server Message-ID: References: NNTP-Posting-Host: static-69-95-181-76.mad.choiceone.net X-Trace: jacob-sparre.dk 1174706268 22900 69.95.181.76 (24 Mar 2007 03:17:48 GMT) X-Complaints-To: news@jacob-sparre.dk NNTP-Posting-Date: Sat, 24 Mar 2007 03:17:48 +0000 (UTC) X-Priority: 3 X-MSMail-Priority: Normal X-Newsreader: Microsoft Outlook Express 6.00.2800.1807 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 Xref: g2news1.google.com comp.lang.ada:14629 Date: 2007-03-23T22:19:21-05:00 List-Id: wrote in message news:GYydnepKEqaRFJnbnZ2dnUVZ_uqvnZ2d@comcast.com... > > Wherever I wanted to be able to expand the source code > > with additional documentation, I included a > > > > --{file-name} > My problem is that I don't go back to yesterday's code that wasn't > throw-away after all and comment it, or go back to last month's library > routine that was easily readable by anyone working in last month's > context, and expand on its comments. I would have to be forced, > or at least "re-educated". I find that going back and expanding comments is a fool's game, because by the time the need is obvious, it is too late to do a good job (at least without wasting a lot of time relearning the code in question). Here's what works for me: (1) Throw-away code doesn't need to be commented, but then it must be thrown away. That means immediately. I find the latter hard, so I hardly ever write throw-away code (most of it is still on my computer somewhere - or on one of my older computers...). (2) Code that isn't likely to be used frequently gets commented in critical places, and every subprogram gets a basic description. I use good names and the like, so it will be possible to figure it out again in the future. After all, a lot of Ada code doesn't need comments if the entity names are decent. (3) If I find myself working on/reusing older code, if I find the comments inadequate, I immediately improve them so that they make more sense. (Once I figure out what is going on, of course.) Once you've used something twice, it's a pretty good bet that you'll use it a third time - so don't even think about delaying about improving the comments and other documentation. After all, having insufficient comments the first time is understandable; it isn't possible to predict what will be hard to understand in the future. But once you have an firm answer to that question, failing to act on it is silly and unprofessional. If you really wanted to be forced to do something, it should be to throw away throw away code. Keeping it around is more likely to be harmful than helpful (especially if it is totally uncommented). Randy.