Re: Is there a way to do large block of source code comments

[Niklas Holsti <niklas.holsti@tidorum.invalid>]

On 14-09-01 20:24 , gdotone@gmail.com wrote:
> the book i'm using to learn ada has a little age to it. comments are done with --

Still the case.

> . and the authors suggest 
> 
> ----------
> --|
> --|
> ----------
> 
> for block comments or banner comments.

I use a simpler form for banners:

   (two blank lines)
   --
   ---   <banner heading/title>
   --
   (two blank lines)

Then I have an egrep script with the pattern

   '^ *(---|type|function|procedure|package|generic)'

which produces a nice, compact table of contents of a module.

I see no need for a special formatting of "block" comments, if by that
you mean comments extending over several lines of text.

<pet-peeve>
One of the worst mistakes in the programming field is the choice of the
name "comments" for the in-source documentation and description.
"Comments" suggests something secondary, incidental, unstructured,
incomplete. In-source documentation and description should IMO be
considered as or more important than the formal source code, should be
intentional, structured, grammatical, and complete (to some selected
criterion of completeness).
</pet-peeve>

> just wondering, has there been an addition to the language
> that has created something special for multiple line commenting.

No, fortunately IMO :-)

IMO, one of the best improvements in the C standard, lately, is the
inclusion of "//" comments.

> is there a way to handle several lines at a time without having
> to do -- on every line?

Only if you build your own preprocessor, or use the C preprocessor.

What is nice is to have an editor that can adjust/fill paragraphs in
multi-line comments, while keeping the "--" in their place. I believe I
once had such an editor, but my current ones do not have this ability.

Several C coding standards I've seen suggest that multi-line comments
should use the form:

   /* bla bla
    * more bla bla
    * even more bla bla
    */

which is no less onerous than the Ada "--" prefix, and uglier IMO.

-- 
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
      .      @       .