There is something that could boost productivity and learning curve of
new developers by a factor of three at least and all needed
infrastructure (at least the hardest parts) for this feature seem to
be implemented and working already, it is just not (yet) used to its
full potential.
I have one suggestion and one complaint, they closely belong together
and implementing the suggestion will help improving the situation I am
complaining about by introducing a great *reward* for the needed (and
currently lacking) discipline of documenting the source code. Yes, let
me repeat this enormous frivolity: "documenting the source code!"
If the option "show declaration hints" in options->editor->automatic
feaures is activated (seems to be default) then it will show a little
hint window whenever the mouse hovers over an identifier and it will
display some information that it can parse out of the source about its
declaration.
The most important GREAT feature of this little popup window is that
it will show the (* COMMENT *) that immediately precedes the
declaration.
(* return the foo of the something for the given bar.
Will be called by foobar on every foobaz event. The
x component will be cached after the first call so it
does not cost anything to call this on every foobaz*)
function TSomething.GetFoo(bar: TBar): TFoo;
begin
// [...]
end;
It will show the text of the above comment when hovering the mouse
over any occurrence of this method call. This is a GREAT feature.
Now here comes my complaint: 99% of all code in LCL and Lazarus seems
to be completely undocumented, in some places there are thousands of
consecutive lines without any single comment, types and variables and
method after method with funny names, obscure parameters and obscure
return values are declared without any mentioning of what they might
be good for, *who* or what kind of code at the other end of the
project might use them and *when* and *how* and under what
circumstances.
Suggestion: Make this hint window even more useful by letting it also
pop up for the currently highlighted item in the *autocomplete* list
(other IDEs like Netbeans or Eclipse are doing the same) and then
people might start seeing the ***usefulness*** of putting a small
descriptive sentence above every method about what it does or how it
is used and also sometimes even a whole paragraph of documentation for
not so obvious things.
Make everything you could possibly do to further increase the reward
for the "burden" of documenting source code.
Documenting code is really not as hard as it seems, I do the same
thing with all of my code in all languages I use. Whenever something
finally works and I can lean back and proudly look at the functions,
classes or methods that had cost me some nerves to implement I start
writing some lines of explanatory text about this adventure, trying to
formulate what is going on like i would explain it to somebody else.
Sometimes more than 50% of my code is only documentation. sometimes
only 3 words per method, sometimes 10 lines explaining why the method
is needed and why it is implemented exactly the way it is and maybe
some words about its side effects.
I don't use any of the fancy javadoc parameter declaration stuff that
is available in some languages, redundantly declaring things that are
already obvious from the function signature a second time would indeed
be a burden, i just write a text comment for every class and method
containing things that are not obvious.
If Lazarus can display such comments in all places where this might be
appropriate (it does already in some places but in the autocomplete
list it would be obviously useful but is still missing¹) I am sure
that people would start commenting their code.
_________
¹ If nobody wants to implement it then I will try to make a patch for
it myself (and comment it!), once I have successfully found my way
through the undocumented synedit code (or wherever this might be
located, it is not easy to find, its all completely undocumented)
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
