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

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

On 14-09-01 23:34 , G.B. wrote:
> 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.

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