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

[Martin]

On 24/07/2010 14:14, Bernd wrote:
> You came up with the AVL tree and the only place where AVL is
> mentioned (I did a search on identifiers) anywhere in the IDE was the
> code folding thing.
>
> I have never written a folding text editor in my whole life, so I have
> no Idea what possible alternatives have proven to be useful for
> implementing such a thing nor can I spontanuosly imagine how a tree
> structure (why/how is it a tree?) might be useful here.
>    
Because comparing the cost of computing ("Big O" [1]) for inserting, 
deleting or looking up information is reasonable low (and memory 
footprint acceptable)

Say you store a flag on each line: visible/invisible:
   insert/delete => fast O(1)
   lookup => slow O(n)  // n= amount of line
   => e.g computing the amount of folds before the 1.000.000 line => 
loop through all of the lines

avl tree all operation a O(log n)  //n amount of currently folded areas)
(A bit slower in the IDE , due to nesting)
   => e.g computing the amount of folds before the 1.000.000 line 
(assuming each line has one fold) => go through 20 nodes
      [and if there are only 100 folded sections, in the first 1000000 
lines => go through 7 nodes]

 From the examples you can see the difference in time needed to compute 
certain information

[1] http://en.wikipedia.org/wiki/Big_O_notation

----
The above explanation of course is only meaningful if you already know 
about such structures and algorithms and big o ......

Tto proper document it, is a huge amount of work...

> The audience for code and comments that make up the application itself
> is of course the person who comes to the project and wants to start
> working on its implementation. I don't know whether the Lazarus
> Project wants to attract new developers or not. If this is the
> intention then there should be documents that describe what concepts
> are used and how all the parts play together. And for you as a
> programmer who knows it all already would be easiest to write a few
> lines for every class and maybe also a few lines for every unit or
> about the architecture of a bigger part as a whole.
>    
Now we switch topic => there is no doubt that docs are needed. (And yes 
new contributors are always wanted, so this underlines the point)

But a new contributor can equally read comment or fpdoc. Assuming he 
uses the IDE, and it's setup correctly, both will show up as hints.


> Let me repeat it: The audience for documentation is people who have
> less knowledge about the architecture than you and also new
> programmers who might be experienced and might *know* exactly what an
> AVL tree is but still have no clue *why* the hell there was such a
> tree chosen for exactly this problem (what problem?) and how exactly
> it is utilized *without* sitting down for a few hours studying and
> debugging the code until they find out what could have been written in
> 3 or 4 simple sentences by the initial developer.
>    
Half agreed, an AVL tree is well known, and if you do not => wikipedia 
=> no need to put that in code.

why it was chosen may not even matter => it was, there are 100 of ways 
of doing it, one was chosen.
And anyway => explaining this, will take more than a feew lines fitting 
into a comment

> The code is in large parts a completely undocumented mess! It is
> absolutely no fun to read it!
>    
Nothing to do, with the question comment or fpdoc
but as above, no disagreement on the need of docs.

And for as long as they are absence => ask on this mail list, and if 
anyone knows you will be answered

> You can either chose to keep it a 3 man show of only a handful of
> people by not sharing any of the secret knowledge with ordinary
> mortals like me or you could chose to finally start *documenting* what
> you have done already in a way that is commonly agreed upon amongst
> developers how such complicated code should be documented and people
> will be able to learn how all the many parts of the IDE are working
> together and new developers might be able to join to the project.
>    
I agree, and yet unfortunately it want change much (not immediately anyway)

And there are plenty of other mailthreads 100 of mails explaining the 
need, and whys, and pro and contras of various ideas/needs => and even 
after a 100 mails nothing changed.

Everyone know, and knew the need for docs. Some has been done, others 
has not. Being reminded of this need, doesn't change this.
I have started a few bits on synedit, very little yet. Simply because 
most of the time I rather write new code => I do it in my spare time, I 
don't get paid, I like to do, what I feel I want to do most....

And when it comes to docs, most of them are about, how to use it in your 
app => and there are some docs for that, but the next issue is they are 
hard to find. Lot of it is on the wiki.

It's a catch 22 => I agree with you, yet I aint going to do anything 
(well, not any more than I would anyway do)

------
As I said, for now, rather than discussing, what everyone knows => ask 
questions what you actually want to know. That is much more productive 
for everyone