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=unavailable autolearn_force=no version=3.4.4 Path: buffer1.nntp.dca1.giganews.com!border1.nntp.dca1.giganews.com!nntp.giganews.com!usenet.blueworldhosting.com!feeder01.blueworldhosting.com!feeder.erje.net!eu.feeder.erje.net!fu-berlin.de!uni-berlin.de!individual.net!not-for-mail From: Niklas Holsti Newsgroups: comp.lang.ada Subject: Re: Is there a way to do large block of source code comments Date: Mon, 01 Sep 2014 22:08:21 +0300 Organization: Tidorum Ltd Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-Trace: individual.net Qa+jZSWwfEB6uRDlmbmXbwLTDgB55zFgyk3YxTR3hSSj/IEHJr Cancel-Lock: sha1:kj0lkIK2pk8iNv0OMCGlNNZ+VXs= User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:24.0) Gecko/20100101 Thunderbird/24.6.0 In-Reply-To: Xref: number.nntp.dca.giganews.com comp.lang.ada:188784 Date: 2014-09-01T22:08:21+03:00 List-Id: 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) -- --- -- (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. 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). > 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 . @ .