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

[Martin]

On 23/07/2010 18:53, Bernd wrote:
> 2010/7/23 Martin<lazarus at mfriebe.de>:
>    
>> but then for the more experienced reader any comment explaining the obvious
>> "to him" just is in the way of the big picture.
>>      
> No. This is simply not true. Comments in the code are not for
> yourself, because then you would not have to write any comments since
> *you* already know how it works. Comments are for *other* people who
> might later read your code and don't yet know how it works.
You misunderstood me. Still I stand by my words: "it depends on the 
experience of the reader.

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.

So do I expect the reader to know "well known" data structures, design 
pattern, and similar? and where does "well known" start? That term has a 
different meaning for everyone.

> I cannot
> believe that we are seriously discussing the helpfulness or necessity
> of comments and that there could be any doubt about it. Of course
> comments are *always* helpful! There simply is no reason to leave them
> away, unless you intentionally want nobody else to ever read or
> understand the code.
>    
again an example
(the example is incomplete, it doesn't handle the case of an empty array 
=> anyway: it's an example)

   m := SomeArray[0];
   for i := 1 to length(SomeArrar) do
     if SomeArray[i] < m then
       m := SomeArray[i];

Quite readable, and I know at a glance what it does, I need no comment 
there.

In fact I doubt that the following is more readable, or if part of a 
longer stretch of code, if it would increase the readability of the 
overall code (spreading it out, makin less of it fit on your screen

   // Start with the first value of the array.
   // This value will then be compared to all other values in the array 
to see if any of them is smaller
   m := SomeArray[0];
   // start comparisation with 2nd value (index=1) of array,
   // since we already read the first value
   for i := 1 to length(SomeArrar) do
     // check if it is smaller than the smallest value found
     if SomeArray[i] < m then
        // if it is, replace the smallest value found by the new 
smallest Value
       m := SomeArray[i];
    // Now m is the smallest value that was found in the array

Don't say those comment are silly.

I said it depends on the level of the reader. I fthe reader of the code 
is a total beginner, who hasn't done more than "hello world" then he 
will need all of those comments. But certainly to anyone (but the 
beginner) readability went down.

Now yes this example may be a bit far fetched. But at any level of code 
complexity (assuming it is written in a clean style), there are people 
who look at it and understand it at a glance, and people who need more 
or less comments.

So the same comment will be useful to some, and useless (if not counter 
productive) to others (and by others I don't mean the original author of 
the code)

> How can a comment ever be in the way? If it tells you nothing new you
> simply ignore it. We are talking about small comment blocks at the
> method headers. How can 2 or 3 light green lines *above* a procedure
> definition or above the class definition come into your way while you
> are working *inside* the procedure body?
>    
- What if I don't have syntax highlighting?
- what if I compare the code o this procedure, to the code of the one 
right before => then the comment means I have to scroll more
- what if I search for some identifier, and my search results contain 
many lines in comments, where the word is used as English word and not 
at all related to the identifier I was looking for?

>
> fpdoc forces everybody who wants to read the code to use Lazarus
> because otherwise half of the code is missing ("half of the code"
> meaning the comments that IMHO are substantial part of any readable
> code).
>    
fpdoc can be compiled into chm and other help formats => allowing you to 
open the help in a window next to your code editor.

But yes, whatever method you choose, those who do not like it have to 
suffer.
Some people suffer if it is comments, other suffer if it is fpdoc

One point we can probably agree on:
Everybody suffers, if there is no doc at all