[Asterisk-Dev] Need help to get into the code

[Bob Carlson]

This RTFC (Read The F* Code) attitude I see here is really self-defeating.
Open source is a collaborative enterprise and putting adequate commentary
into the code is simply a more efficient way to run the enterprise.

I believe Kevin said that he always comments code that is not
self-explanatory and provides documentation by and for developers. He
considers the existing comments to be sufficient for a "non-casual" reader.
I believe it was also Kevin who was using an example of dial plan code. He
said something to the effect that "If you just know the context of dial
plan modules, you don't need any commentary." This is exactly the problem.
The comments that are missing are those that provide the context, the
overview. No one, least of all me, wants comments of the variety "i++; /*
increment counter */". I want to know the intent behind the interface, the
rules, the options and the illegal combinations.

I do not want to flame anybody, just give some honest feedback. In my
experience, the commentary in Asterisk is insufficient for a good
developer. We all suffer from it in several ways. It slows down the process
of improving Asterisk. It introduces bugs because developers are not aware
of rules they should be following in implementing types of resources. And
finally, it results in more (and more basic) inquiries here on this forum
to annoy the "experts".

Let me give a specific example. I have developed a new channel over the
past couple of months. I think that makes me a non-casual reader of the
code. I researched the Wiki, read the code in many channel modules, read a
lot of the code in channel.c and thoroughly went through channel.h.
Channel.h was one of the first places I looked, because it was exactly
where I expected to find the "context" mentioned by Kevin. But there is
very little explanation in channel.h or anywhere else of what is required
of a channel module or the options available to a channel module. I had to
infer all this from reading various chunks of code and fragmentary
comments. I have a working channel now, but I really do not know what bugs
might be lurking because I do not know what the rules are behind the
channel interface. BTW, much of the channel.c code is NOT self-explanatory.

I would estimate that 100 to 200 lines of comments in channel.h could have
reduced my development time by about a third. Who knows how many bugs I
have introduced because I do not have this information? The right person to
create and maintain this commentary is the person who creates and maintains
the interface, not someone who reads the code and THINKS they understand
what it all means. As important as anything is the intent behind features
of the interface. Only the developer of the interface knows that for
certain.

I was also caught by the recent change in the channel interface. I believe
the message on this forum was "take a look at the channel modules I changed
to see what was updated." This was not helpful. Once again, a simple
bulleted list of perhaps 10 lines total would have cut in half the time I
(and presumably many others) spent updating my module.

I want to appeal to your self interest here. A little time spent adding
comments in the right places will result in faster development of asterisk
and better quality in the result, something I think you want.

Cheers, Bob