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

[Preston Garrison]

You know something that is highly overlooked is learning to write 
understandable code.  Alot of programmers like to write code that is a 
mess to understand.  Just because you can do something in the C 
language doesn't mean you should :)  However i have to admit out of all 
the open source projects, asterisk has some of the easiest to 
understand code.


-----Original Message-----
From: Andrew Kohlsmith <akohlsmith-asterisk at benshaw.com>
To: asterisk-dev at lists.digium.com
Sent: Tue, 1 Mar 2005 21:12:36 -0500
Subject: Re: [Asterisk-Dev] 'tonezone' in chan_zap.c

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.
_______________________________________________
Asterisk-Dev mailing list
Asterisk-Dev at lists.digium.com
http://lists.digium.com/mailman/listinfo/asterisk-dev
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev