[Lazarus] help writing help [was: Re: Re: Suggestion for TRadioGroup documentation]

Martin Frb lazarus at mfriebe.de
Fri Apr 8 20:36:02 CEST 2016


On 08/04/2016 19:24, Jürgen Hestermann wrote:
> Am 2016-04-08 um 18:18 schrieb Martin Frb:
>> Or the person reading the code with the intend of documentation, is 
>> more clever than this. They could report any suspicious parts, and 
>> clarify the intend. That way the code would be additionally be 
>> checked for bugs.
>> Bugs where the original implementer may have had a wrong 
>> understanding of what he was doing. In which case had the original 
>> coder documented it, the bug would have gone into docs.
>> Assuming the original coder is available for comment, then a person 
>> different from that coder can often write much better documentation. 
>> (simple because then 2 (or more) people will have though about what 
>> it should be)
>
> I aggree  that this can happen.
> But it requires that the reader has at least the same skills
> regarding the topic of what has been coded.
> How long do you think would it take to (fully) understand the code for 
> VirtualTreeView?
> I have already found bugs in it but never understood why they occur
> because I do not understand how the whole unit is coded.
> So how should I even write documentation for it?
>

I have maintained SynEdit for nearly a decade now. Yet there is code in 
SynEdit I never looked at, and consequently I have not understood yet. 
According to you, it is a good thing I have not tried to add any docs. 
(Actually I should delete the parts I added to the wiki)

On the other hand according to me, anyone could have investigated a 
single property, or method. To do so would not require an understanding 
of everything. Yet that person could have documented the one 
method/property.
If so then at least some parts would have docs.

On VirtualTreeView: I dont know if the Author is around, and if he 
could/would answer questions, or even proof read contributed docs. But 
if he was, then the question  "How long do you think would it take to 
(fully) understand" is just the wrong question. The question should be: 
how much time do you have? Is there a chance, that in that time you can 
document at least one property or method? If yes, well then start. If 
you get more done (now or later), then even better.

The problem is, everyone (including me) is very good at pointing out why 
someone else should do it. And everyone just keeps pointing out it needs 
to be done.
Well that is fine. Lobbying for a cause is great. But the expectations 
in that case must be set correct. Someone else may also have a reason 
not to do it.




More information about the Lazarus mailing list