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,2a687662f09731bb X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news1.google.com!news1.google.com!newsfeed.gamma.ru!Gamma.RU!newsfeed.icl.net!newsfeed.fjserv.net!news.tele.dk!news.tele.dk!small.news.tele.dk!newsfeed1.swip.net!swipnet!newsfeed1.funet.fi!newsfeeds.funet.fi!feeder1.news.jippii.net!reader1.news.jippii.net!53ab2750!not-for-mail From: Niklas Holsti Organization: Tidorum Ltd User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.8) Gecko/20050513 Debian/1.7.8-1 X-Accept-Language: en MIME-Version: 1.0 Newsgroups: comp.lang.ada Subject: Re: Request for comments on simple Ada program References: <87psp1lsc4.fsf@willow.rfc1149.net> In-Reply-To: Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Message-ID: Date: Wed, 16 Nov 2005 11:03:12 +0200 NNTP-Posting-Host: 81.17.205.61 X-Complaints-To: newsmaster@saunalahti.com X-Trace: reader1.news.jippii.net 1132135725 81.17.205.61 (Wed, 16 Nov 2005 12:08:45 EET) NNTP-Posting-Date: Wed, 16 Nov 2005 12:08:45 EET Xref: g2news1.google.com comp.lang.ada:6423 Date: 2005-11-16T11:03:12+02:00 List-Id: Jacob Sparre Andersen wrote: > Writing the function of the procedure in a comment is OK, although I > would like to keep all the non-checkable stuff outside the source > file. > > Jacob (who believes that the optimal comment/code ratio is zero) People differ. In my Ada code, the "comments" average 33% of non-blank lines (59% for package specs, 23% for package bodies, and note that I never repeat comments from specs in bodies). I still occasionally find it hard to *fully* understand code from a couple of years back. It's not the details -- I know what N := N + 1 means by itself -- but the background assumptions, intentions, limitations, usage rules, interactions. I put "comments" in quotes above, because I think that this is a bad case of mis-naming in programming language terminology. The word "comment" implies something skimpy, an addition, a note; in my view, what is needed is a rationale, description or motivation that is mainly written *before* the code itself. As for keeping such text in separate design documents, I would do it if a customer demanded it, but I think it would be much harder to manage changes, versions and configurations accurately. Still, some very high-level descriptions are nice to keep apart from the source-code, if they are not outdated by day-to-day code changes. -- Niklas Holsti Tidorum Ltd niklas holsti tidorum fi . @ .