[Lazarus] comments in source [Re: "show declaration hints" has more power in it than is really used]

[Mattias Gaertner]

On Sat, 24 Jul 2010 14:24:15 +0200
Bernd <prof7bit at googlemail.com> wrote:

> Also I have noticed that in many of the rare occasions where a class
> has a documentation like here:
> 
>   { TSynTextFoldAVLTree
>     Nodes in the tree cover the folded lines only
>     the cfCollapsed line at the start of a fold, is *not* part of a node.
>     RemoveFoldForline has special precaution for this.
>   }
> 
>   TSynTextFoldAVLTree = class
> 
> It is used the wrong way. The empty line will make make the comment
> effectively invisible for the hint- or help system and also there are
> many comments that consist only of the name of the class that follows
> afterwards:
> 
>   { TSynFoldNodeInfoHelper }
> 
>   TSynFoldNodeInfoHelper = class
> 
> SUCH comments are indeed annoying because they are not only redundant,
> they are completely unnecessary. The abuse of comments as some kind of
>  "bookmarks" or separators to be able to quickly scroll until the next
> green line appears and something ends and something else starts serves
> no purpose. Therefore better tools exist. Comments are meant to
> *explain* things, not to draw horizontal lines into the code that are
> only meant as separators and to be visible during fast scrolling from
> 2 meters distance.

You can turn the auto creating of class headers off in the options.

There are many different coding styles and so there are many different
commenting styles.

See here:
http://wiki.lazarus.freepascal.org/Lazarus_IDE_Tools#Hints_from_comments

Note:
A class header is the comment in front starting with the class name.
There can be code in between. For example:

type
  { TMyClass ... }

  TMyEvent = procedure of object;

  TMyClass = class
    ...
    property MyEvent: TMyEvent ...
  end;

Some people use the class header for scrolling or for
beautification, others add some text. It is up to the programmer/boss to
decide what fits best.


Mattias