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: border1.nntp.dca1.giganews.com!nntp.giganews.com!usenet.blueworldhosting.com!feeder01.blueworldhosting.com!feeder.erje.net!eu.feeder.erje.net!news2.arglkargh.de!news.swapon.de!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 23:53:59 +0300 Organization: Tidorum Ltd Message-ID: References: <1285756762431293678.582499nonlegitur-futureapps.invalid@reader80.eternal-september.org> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Trace: individual.net ZwXsneQ2nxEAVhuHJuGlVwonUxlbRCmPzKpa6R1KNlSFUYr0nO Cancel-Lock: sha1:jr1VxRq5+j/zHPIuKGcofYkZnjM= User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:24.0) Gecko/20100101 Thunderbird/24.6.0 In-Reply-To: <1285756762431293678.582499nonlegitur-futureapps.invalid@reader80.eternal-september.org> Xref: number.nntp.dca.giganews.com comp.lang.ada:188788 Date: 2014-09-01T23:53:59+03:00 List-Id: On 14-09-01 23:34 , G.B. wrote: > Niklas Holsti wrote: > >> >> 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. > > The notions once associated with commenting suggest rather the > opposite of incidental, unstructured, or incomplete. Writing commentary, > before the age of computers, indicated the highest degree > of professionalism, both as regards the subject on which the comments > were made as well as the forms of treatment. Yep. But still "secondary", such as commenting on a work by some famous author -- it may require high expertise, but the comments are not meant to stand alone or have equal standing with the original work which is being commented. > So it is the programming profession that has neglected what commenting > should mean. Perhaps it was a mistake to drop the word "comment" > from most languages after Algol 60 instead of trying to formally extend its > possibilities. Nah - the word "comment" for in-source description should be replaced by something better, both in writing and in speech. > Ada 2012 aspect notation could add a tool-ready aspect that describes > an entity in brief: > > procedure Read (..., Item : out T) > with Comment => "... short description ...", That could be useful for ASIS tools (although I believe that ASIS already has some way to access the comments for a declaration), but I would object to using the word "Comment" as the aspect name, for the reasons I have given. -- Niklas Holsti Tidorum Ltd niklas holsti tidorum fi . @ .