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).
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
