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!news3.google.com!news.glorb.com!news.banetele.no!news.szn.dk!news.jacob-sparre.dk!pnx.dk!not-for-mail From: Jacob Sparre Andersen Newsgroups: comp.lang.ada Subject: Re: Request for comments on simple Ada program Date: Wed, 16 Nov 2005 15:21:06 +0100 Organization: Jacob's private Usenet server Message-ID: References: <87psp1lsc4.fsf@willow.rfc1149.net> NNTP-Posting-Host: hugin.crs4.it Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: jacob-sparre.dk 1132150867 29390 156.148.71.67 (16 Nov 2005 14:21:07 GMT) X-Complaints-To: sparre@jacob-sparre.dk NNTP-Posting-Date: Wed, 16 Nov 2005 14:21:07 +0000 (UTC) User-Agent: Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux) Cancel-Lock: sha1:V7XRiJKPA1L6PslYrbGRA3OfYZU= Xref: g2news1.google.com comp.lang.ada:6431 Date: 2005-11-16T15:21:06+01:00 List-Id: Niklas Holsti wrote: > 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) > > 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). My numbers are 33% in specs and 18% in bodies (22% in total), but I consider them to be too high. 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 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. That can happen to me too - and to almost any other programmer too, I suppose. > 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. 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? > 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. I always keep the design documents separate (when they exist ;-), but I must admit that programming for research purposes is a bit different from commercial software development. Jacob -- "Human beings just can't not communicate."