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

[Bernd]

2010/7/23 Martin <lazarus at mfriebe.de>:
> Example:
>
> I may declare a class:
>
> TAVLTreeNode = class
>  FLeft, FRight, FParent: TAvlNode;
>  FBalance: Integer;
> end;
>
> - Now if the reader knows what an AVL tree is, there is no comment needed,
> it is perfectly self-explaining.
> - If the reader doesn't know, but does know what a tree is, then I only need
> a comment for FBalance.
> - And if the reader doesn't even know what a tree is, then I need a hell lot
> of coments...
>
> So what amount of comments is right? and how many lines should it have?
> If I put a 20 line explanation in ther about AVL trees => then any
> experienced reader will be annoyed.

It seems you misunderstood me too. There are two types of comments,
the ones that explain the "how" or the "what" and the ones that
explain the "why".

The "what" and "how" can be left away if the code is clearly written
and identifiers have speaking names. It is visible in right in the
editor window by simply lloking at the code *what* it does and also
*how* it does this.

The comments that are needed are the *why*, these explain things that
are not visible when looking at the code that is in front of you. The
example with the AVL tree is not very good. If AVL trees were used
everywhere all over the place then there would no comment be needed at
all, if it was implemented to solve one specific problem then maybe
something like

(*Implements an AVL tree*)
TAVLTreeNode = class
  FLeft, FRight, FParent: TAvlNode;
  FBalance: Integer;
end;


and somewhere else:

(*This tree holds the <dont know>. the basic idea is that every
node represents a <dont know> and we also store the
<dont know> so that we can then easily <dont know>
This tree is created by <dont know> immediately after <dont know>
and used to <dont know> by <dont know>*)
TSynTextFoldAVLNodeData = Class(TAVLTreeNode)
  public
  [...]

As soon as the declaration is bigger than 1 page on the screen it
should have such a comment that describes in a few words what it is
meant for and things. If it is a central cornerstone of the
architecture it would not hurt to describe the purpose and the
intention even more verbose.

This is all I am asking for in all these classses that serve only very
specific purposes and are used in a very special way and sometimes
also in not very obvious containment hierarchies at runtime. It would
greatly help to be able to quickly see where and for what purpose this
class might be used. If only every class had such a short description
mentioning its purpose and the place and the role it will have at
runtime, where its instances will live and how long. It would be so
much easier to understand the whole picture and I cannot imagine that
anybody would ever be annoyed by this.

Don't document what is there (this is obvious by scrulling down and
reading the code) document why it is there and from where and how it
its used.