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!news4.google.com!border1.nntp.dca.giganews.com!border2.nntp.dca.giganews.com!feed.cgocable.net!news.tele.dk!news.tele.dk!small.news.tele.dk!multikabel.net!feed20.multikabel.net!border1.nntp.ams.giganews.com!nntp.giganews.com!feeder2.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: <6GKef.9227$yo5.3796@reader1.news.jippii.net> Date: Wed, 16 Nov 2005 19:08:50 +0200 NNTP-Posting-Host: 81.17.205.61 X-Complaints-To: newsmaster@saunalahti.com X-Trace: reader1.news.jippii.net 1132164866 81.17.205.61 (Wed, 16 Nov 2005 20:14:26 EET) NNTP-Posting-Date: Wed, 16 Nov 2005 20:14:26 EET Xref: g2news1.google.com comp.lang.ada:6434 Date: 2005-11-16T19:08:50+02:00 List-Id: Jacob Sparre Andersen wrote: > Niklas Holsti wrote: > >>... > >>>Jacob (who believes that the optimal comment/code ratio is zero) On a philosophical level, I agree with you -- writing "comments" is an extra burden, and one risks contradictions between the comments and the code (I recall an article long ago in SIGPLAN Notices with the title "Comments considered harmful" :-) An ideal language should be expressive and readable enough to stand on its own. Unfortunately, Ada -- or, to be fair, the way I use Ada -- is still too low-level for that. Perhaps some future aspect-oriented language... > My reason for mentioning what I believe is the optimal comment/code > ratio, is actually due to an article in ACM Queue, where the authors > used a code quality metric, which equalled more comments with higher > code quality. I agree that such a metric can be very misleading, because then you should measure the quality of the comments, too, which is impossible to automate. But I think anyone who has tried to reuse two code packages, one with (good) comments and the other without, must feel that there is *some* truth in the metric. > But I don't put the rationale in the source code. The rationale is > kept in a separate file. What I still do put in the source code - and > don't like putting there - is the abstracts for the subprograms and > packages. But how can I easily cross-link the documentation (with the > abstracts) and the code (with the implementations)? Should I cite the > package name/full subprogram specification in the documentation to > create the cross-link? Or can somebody come up with a more elegant > solution? There are some IDE-like commercial tools -- if memory serves, some sort of souped-up requirements databases + design tools + code generatorts with "automatic" document generation functions -- that claim to keep these cross-links for you. But burying my code in that sort of a monster machine makes me very nervous, and they aren't cheap either. The conversation seems to be drifting towards Knuth's "literate programming". I think it is or was a good idea, but gave more benefit for Pascal than it would give for Ada, which can be more literate in itself. Perhaps the time is ripe for something like "checkable literate programming", modelled on SPARK, where the annotations/comments are readable and informative but also checkable? -- Niklas Holsti Tidorum Ltd niklas holsti tidorum fi . @ .