[Asterisk-Dev] 'tonezone' in chan_zap.c

[Andrew Kohlsmith]

On March 1, 2005 08:47 pm, alex at pilosoft.com wrote:
> I disagree. At any case, if you can't read code, and you need your hand
> held, you are not likely to be much of a contributor in future.

I respectfully disagree.  If the code is not adequately described by itself 
and the comments therein, the coder is to blame.  "strange" or unintuitive 
code without sufficient comments has NO PLACE in open-source projects.  

> I don't think you understand why people are contributing to Asterisk. We
> are not doing it to help *YOU*. We are not doing it to make the world a
> better place. We are writing code to *solve our immediate need* and
> are gracious enough to share that code with everyone else, including you.

Blow it out your ear -- That kind of attitude *stinks*.  If someone is making 
a decided effort to learn how the code functions and is having trouble, well 
then that is exactly what this list and #asterisk-dev is for.  If you think 
code has to be hard to read to be functional, then your contributions *will* 
be replaced by clearer and ultimately better code by persons who don't have 
this massive chip on their shoulder.

If the programmer thinks his code is so great I suggest he close-source it and 
make millions off it.  Oh wait, he can't, for many different and varied 
reasons, which is one of the reasons he's writing OSS in the first place.  
Open source helps everyone, including the programmer.  Many eyes not only 
make the bugs shallow, but they also help the programmer become more 
proficient in his trade, so long as his ego's not blocking the effort.

> The worst thing you can do is bitch and moan that 'I cannot understand
> this code, it has no documentation blah blah blah'. I [and I think, most
> developers on this list] *simply do not care what you think about our
> code, whether you use it or not use it*. WE DO NOT CARE. NOT AT ALL.

However, said programmer *should* make the effort to describe what it is their 
code is doing if a third party asks what it is it's trying to do and shows 
that he's not only making an effort to understand it, but is also able to 
understand the explanation.

I think that is perhaps why your post irked me so -- You are coming across as 
if the programmer has done some great service to mankind and all should bow 
before him and cower in fear at his lack of comments, as they're simply not 
intelligent enough to figure out what's going on from the obvious code.

If code cannot be clearly understood then it damn well better be commented.  
It takes far more effort for a third party to try and decipher the code than 
it does for Mark or Brian or even me to put a goddamned two-line comment 
explaining what's going on before the code block.  It's one of my greatest 
irks with OSS, and it's something that I've done many times myself...  "The 
code is so obvious, it doesn't need comments," used to be my mantra, "I'll 
never forget what I'm doing here."

Two months later, I'm scratching my head and have the notepad out, scribbling 
down code flow and test data patterns.

Now once a third party's expended that energy or gotten the original author to 
explain what's going on, his greatest service to the project would be to 
submit a patch (hopefully which Mark will accept) which is nothing more than 
a comment block describing the function/algorithm/condition test that was so 
confusing in the first place.

This is where OSS shines.

-A.