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

[Bernd]

2010/7/24 Martin <lazarus at mfriebe.de>:
>  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).

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.

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.

Who else but *you* or those who wrote the code should be able to write
this? If you dont do it who else should do it? This should IMHO have
highest priority: Stop all coding and start documenting what you have
done so far until there is enough prose to read to have an overview of
all the parts of the IDE and how they play together.

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.

The code is in large parts a completely undocumented mess! It is
absolutely no fun to read it!

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.