[Bf-committers] Summer of Documentation

[trip somewhere]

I could go on about where things are weird there.. Like take comments
with a grain  of salt, patches are ment to be tested before they hit
cvs and so on..

My question then is can we get this subject into a stream along with
the Summer of docs ? There apparently is only one real way to comment
code then but it needs to be done somehow. It will help the future of
Blender and the new commers,


> Here, I'll make a very simple example so you can
> actually understand it. Read carefully.
>
> - Coder A writes some code in Blender doesn't put any
> comments (sadly).
> - Coder B looks at Coder A's code, thinks he gets it
> and add comments (which are incorrect).
> - Bug gets reported in the tracker.
> - Coder C sees the bug report, looks at the code and,
> based on the comments there, makes a "fix" that breaks
> everything in certain cases, because Coder B
> understood enough to get the general idea, but not the
> special cases.
> - Nobody understands where the problem is since it
> "should" work, because the comments say that's how it
> works, so it must be true.
> - Coder A gets back from where ever the hell he was,
> curses a lot about people touching code they don't
> understand and fixes both the original report and the
> bugs derived from B's erronous comments.
>
> The solution/problem is twofold:
> 1- Coder A should have documented his code.
> 2- Coder B shouldn't have documented code he didn't
> understand, creating more problems than it solved.
>
> > I just dont see the big issue
> > here to not have more of them.
>
> The "issue" is most definitly not to have more of
> them.
>
> Martin
>