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!news3.google.com!border1.nntp.dca.giganews.com!nntp.giganews.com!local01.nntp.dca.giganews.com!nntp.comcast.com!news.comcast.com.POSTED!not-for-mail NNTP-Posting-Date: Sat, 24 Mar 2007 02:35:59 -0500 From: tmoran@acm.org Newsgroups: comp.lang.ada Subject: Re: commenting, was Re: Use of declare blocks References: X-Newsreader: Tom's custom newsreader Message-ID: Date: Sat, 24 Mar 2007 02:36:00 -0500 NNTP-Posting-Host: 67.164.83.70 X-Trace: sv3-VUtQbQG4nCqZAyLXTuGNsYfpjrIKa8iobKZK0d65esNNDD0qjG+xMAnNI2ZlP69gWY/MouU98olthFc!4hg8OImOSe8VubdH8xuh7wBjtKG5c/fw9G7FJgEb6sRSr0O562qR5CjcnzUtksAqGdujRACFZXKY!z6U4uAlh6wvrVDwGUc4QxCdlDBcM X-Complaints-To: abuse@comcast.net X-DMCA-Complaints-To: dmca@comcast.net X-Abuse-and-DMCA-Info: Please be sure to forward a copy of ALL headers X-Abuse-and-DMCA-Info: Otherwise we will be unable to process your complaint properly X-Postfilter: 1.3.34 Xref: g2news1.google.com comp.lang.ada:14630 Date: 2007-03-24T02:36:00-05:00 List-Id: I think we mostly agree. It's bad to have a machine cluttered with files, or code, that you think might be useful, but in fact it's so poorly described that it can't be found, or understood when it is found. So the system should force throwing away such things. If you truly think you might need it in the future, you should adequately describe it now, before you've forgotten. Sometimes you know the code or file you are creating is "for the ages" and you spend the necessary time thoroughly documenting it. But often you don't know for sure, and think the likelihood of future use is low, so spending a lot of care is a probable waste of time. Minimal documentation is then appropriate. Rather than having two levels - minimal docs/full docs - and going from level 1 to level 2 when you need the program the second time, I suggest several levels, with transitions dependent on your estimate of the likelihood you'll need it again, and the rate of decay of your memory. For example, in developing a binding to some API, I do a lot of throw-away programs to test that I understand the API calls correctly. I then document the binding. But then a few years later, on some newer project, I recall "I once did a program that did much of what I need now, I wonder where that old program might be." I'd like to either know that program is definitely long gone, don't waste time looking for it, or else have a file description that lets me easily find it, and internal documentation that makes it easy to refresh my memory, to help with today's project.