[Bf-committers] Summer of Documentation

[Campbell Barton]

Davide Vercelli wrote:
> Speaking about code comments, what is really needed are commented
> struct fields. The biggest problem I have in understanding the code is
> when I have no clue about what a variable means... Imho a policy
> requiring a short description and usage note per field should be
> enforced on new code. Adding them to current code (at least when names
> are not auto-explicative) would be a good idea too, but maybe, as
> theeth points out, that should be done by experienced developers.
>
> About Summer of Docs: it's a nice idea, but isn't there the risk that
> it will discourage other, not-paid, documentation efforts?
>
> UncleZeiv
>
If somebody is savvy enough to look up members of a struct, see how 
there used in other areas of the code and comment them.
This isnt that big a deal, and would save others time doing the same 
thing when each new person tries to understand how struct variables are 
used for the first time.

Agree with Theeth that a bad commentis worse then no comment, but this 
savvy person just needs to be carefull not to comment things they dont 
understand.

They still would not have the bigger picture, but if we do this by 
submitting patches. People who do, can review the comments.

-- 
Campbell J Barton

133 Hope Street
Geelong West, Victoria 3218 Australia

URL:    http://www.metavr.com
e-mail: cbarton at metavr.com
phone: AU (03) 5229 0241