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

[Martin]

On 24/07/2010 12:53, Bernd wrote:
>
> 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".
>    
"why" might not be the best word to describe. "purpose" may be closer, 
but doesn't matter.
> 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
>    [...]
>    

Well but again, the same documentation can be done in any way or place.

We are not talking about the fact that it is currently missing only 
where to place it.

Also to whom to I write the comment?
1) A person who is going to use this class in it's own code?
2) A person who is going to modify the code in the unit of that code 
(extend/change/refactor/fix the class...)

The first person is not normally having to look at the source. In fact 
the first person could just have a ppu file, and no source code at all. 
In which case the first person would rely on the help being in an 
external file

For the 2nd person, I can find equally good argomens for both solutions. 
It's simply a matter of personal taste.

> 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.
"purpose" + "where" + "how long" ....

That again is very quickly growing to more than a few lines of comment.
If properly documented an external help, providing linked references, 
index/overview, etc can be much more powerful than a comment.


Of course a "2 line hint" in a comment, is much better than a none 
existing "2 page explanation" in an external file....

And of course creating an external file, to hold a 3 word explanation 
*rather than having 3 words in a comment) is not very practical either....

----
Anyway for your own classes, you can do as you are pleased => and the 
IDE does show it in the hints => so no problem at all.

For code such as the LCL (or the example you picked from SynEdit) it is 
down to who ever writes the code or docs, to decide where to put them.
And as far as I can see, the bigger matter is not where, but that 
partially they are missing completely...

Martin


----
p.s:
  As for the example you picked ( TSynTextFoldAVLNodeData): you will 
have noticed that there are comments (not implying anything about the 
content/quality) of them.
  As for an explanation of the whole class: I would have simply thought 
that finding an AVLNode, in a FoldTree, anyone looking at it would 
conclude it contains data about one piece of folded code (eg, fold 10 
lines starting at line 255).