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.
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
