[Bf-committers] Summer of Documentation

[Martin Poirier]

--- trip somewhere <trip0o at gmail.com> wrote:

> Peachy sentiments. But say a coder does know what
> the code does like
> you.. Could that coder then kinda comment more ?? Is
> it sin ?

Of course not, I never said I had anything against
comments, per se, what is wrong is people commenting
when they're not sure what the code does, introducing
incorrect comments.

> Comments can always be corrected like a bug and they
> dont kill source
> at all from compiling.
> How is it a bad comment will hurt?

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

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com