[Bf-committers] Summer of Documentation

Campbell Barton cbarton at metavr.com
Mon May 15 09:31:39 CEST 2006

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 

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

More information about the Bf-committers mailing list