[Bf-committers] Summer of Documentation

Martin Poirier theeth at yahoo.com
Mon May 15 03:40:38 CEST 2006

--- 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


Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 

More information about the Bf-committers mailing list