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