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

[G.B. <nonlegitur@futureapps.invalid>]

Niklas Holsti <niklas.holsti@tidorum.invalid> wrote:

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

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. Today, the term still has
a place in law, I think.

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. Eiffel has tried to make it more useful with its "indexing"
clause
at the top of class definitions. Python stores a descriptive comment,
a string, with every def.

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 ...",