Re: Request for comments on simple Ada program

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
      .      @       .
.

Relevant Pages

  • Re: announcement: FriCAS-1.0.0 release
    ... Personally I find the use of noweb distracting. ... unified documentation format across languages ... FriCAS still uses noweb -- new stuff uses plain files but it ... Concerning literate programming I would say that nobody know ...
    (comp.lang.lisp)
  • Re: fortran maintenance tools
    ... put code around every subroutine call to collect performance ... It is one thing to put the effort into improving the code if you end up with something readable, well organized, and with some confidence that the code matches the documentation, another thing all together if the code runs faster but is no easier to understand. ... Literate programming makes it easy to sprinkle comments of the sort that explain why a line of code really does implement equation 73 from that 1952 tech. report, assuming the arguments satisfy the constraints unique to the case under consideration. ...
    (comp.lang.fortran)
  • Re: Writing, Coding, and Professionals
    ... Guy Macon writes: ... Anton Ertl wrote: ... The first contrasts literate programming with 'an ... Contrasts Literate Programming with embedded documentation: ...
    (comp.lang.forth)
  • Re: Plain TeX and long tables
    ... >> there's far less tutorial information available for plain users than ... >> authors deign to describe their packages, other than in the odd remark ... the reason why cataloguing of much of ctan is proceeding so slowly. ... documentation. ...
    (comp.text.tex)
  • Re: Documentation and Useability - a proposed solution
    ... > install it. ... > much more experience that I or any other noobie. ... > My argument is that as a noobie, I have access to packages that are ... > or even be able to seperate the grain from the chaff of documentation ...
    (Debian-User)