[asterisk-dev] Coding guidelines change (proposed)

[Daniel Hazelbaker]

On Feb 27, 2008, at 12:10 PM, Steven S. Critchfield wrote:

> Maybe it is me, but just because you commit in smaller chunks  
> doesn't reduce the chance of error. It just reduced the amount of  
> reverting to reverse the commit.

True, but specifically I am thinking about the ability to

1) have people check over the changed code.  It would (I think) be  
easier to get other developers to look over a 400-500 line diff file  
every month or two then it would be to get people to look over a diff  
file with 10,000-15,000 (with all the lines of context of course) in  
one big chunk; kind of like offering somebody either app_softhangup or  
app_voicemail and asking which they prefer to look over for errors.

and 2) when merging that smaller chunk into a 1.4.x (or 1.6.x,  
whichever) release it is much more likely to find introduced (or  
uncovered) bugs in the release candidate phase when we can specify  
that significant formatting changes were made to the Dial, Hangup and  
Gosub applications.

> Breaking those long functions up might be a good idea.

Agreed, the longer the function the easier it is to make mistakes when  
you change something because you have to make sure it does not effect  
the rest of the function, but that is probably another discussion of  
coding guidelines for another thread. :)

> Commenting is always a good idea, but commenting isn't a janitor  
> project. At least not in my opinion of what janitor projects are  
> meant to do. Janitor projects are nearly mindless code changes.  
> Commenting requires knowledge of what is going on unless you want  
> someone commenting on the obvious.

True, and maybe a "janitor" project is not the right term, but  
obviously the understanding is at least there of what I mean.  I agree  
in some places there will have to be a lot of thought given to exactly  
what the code does, sometimes some digging into specs and possible  
RFCs, I am sure there would be times of discussion on the dev list  
over what exactly a chunk of code does (and how).  But I think getting  
some good comments in will help further development as changes are made.

I will be the first to admit I don't comment my code as much as I  
should, but knowing that I got myself into the habit of at least going  
back over it once a week or so (depending on how much coding I  
accomplished) and commenting the heck out of everything I added or  
modified.  It's pretty easy to remember what and why you coded  
something a few weeks after you did it, after a few months, on the  
other hand, you start questioning your sanity.

Anyway, just food for thought.  As I said I am not volunteering to  
_do_ this project, but it is one of the few (branches) I would feel  
comfortable contributing to as it is an easier project (as compared to  
things like the minivm and such). And it does not necessarily require  
one to have deep knowledge of the internals of Asterisk, one will  
probably gain that knowledge while commenting and other things, but if  
I just don't understand a section and can't figure it out it can be  
left for somebody else that might know better.

> -- 
> Steven Critchfield critch at basesys.com

Daniel Hazelbaker