Asterisk Developer Guidelines

Disclaimer

From the bug tracking page:


In order to keep copyright clean, contributed code needs to be disclaimed. Disclaimers can be found at:

and should be faxed to +1-256-971-6890/+1-256-864-0464 and/or snail mailed to:
Disclaimers, Digium, 6703 Odyssey Drive Suite 104, Huntsville, AL 35806, USA
Either document is fine, just choose the one that makes you most comfortable. Thanks!



Patch format

The following are not official... These are place-holder suggestions! -JP

It is important that patches be easily applied and maintained, so that people can test your code, and it can be easily merged into CVS once tested. Here are some suggestions:

  • Patches should be made against a current, clean CVS checkout.
  • Patches should be made recursively against the full CVS module that it patches.
    • For instance, a patch that affects asterisk/apps/app_queues, and several files in asterisk/sound should be made against the whole asterisk/ tree.
  • Patches should be made with 'diff -Naur OLD.dir NEW.dir'

So, in the above example:

diff -Naur asterisk.old asterisk.new > asterisk-my_descriptive_patch_name-my.patch.version.patch


Assuming that a user has their Asterisk source in /usr/src, this would be applied by:

cp asterisk-my_descriptive_patch_name-my.patch.version.patch /usr/src
cd /usr/src/asterisk
patch -p1 <../asterisk-my_descriptive_patch_name-my.patch.version.patch


Coding Guidelines

NB For the latest info on this, check the file doc/CODING-GUIDELINES in the distribution

  • All code, filenames, function names and comments must be in ENGLISH.

  • Do not declare variables mid-function (e.g. like GNU lets you) since it is harder to read and not portable to GCC 2.95 and others.

  • Don't annotate your changes with comments like "/* JMG 4/20/04 */";

  • Comments should explain what the code does, not when something was changed or who changed it.

  • Don't make unnecessary whitespace changes throughout the code.

  • Don't use C++ type (//) comments.

  • Try to match the existing formatting of the file you are working on.

  • Functions and variables that are not intended to be global must be declared static.

  • Function calls and arguments should be spaced in a consistent way across the codebase.

Function Calls



GOOD: foo(arg1, arg2);
GOOD: foo(arg1,arg2);	/* Acceptable but not preferred */
BAD: foo (arg1, arg2);
BAD: foo( arg1, arg2 );
BAD: foo(arg1, arg2,arg3);


Examples of how code should be formatted



Functions


int foo(int a, char *s)
{
	return 0;
}


If statements


if (foo) {
	bar();
} else {
	blah();
}


Case statements


switch (foo) {
	case BAR:
		blah();
		break;
	case OTHER:
		other();
		break;
}


No nested statements without braces

e.g. no:

for (x=0;x<5;x++)
        if (foo) 
                if (bar)
                        baz();


instead do:

for (x=0;x<5;x++) {
        if (foo) {
                if (bar)
                        baz();
        }
}


Disclaimer

From the bug tracking page:


In order to keep copyright clean, contributed code needs to be disclaimed. Disclaimers can be found at:

and should be faxed to +1-256-971-6890/+1-256-864-0464 and/or snail mailed to:
Disclaimers, Digium, 6703 Odyssey Drive Suite 104, Huntsville, AL 35806, USA
Either document is fine, just choose the one that makes you most comfortable. Thanks!



Patch format

The following are not official... These are place-holder suggestions! -JP

It is important that patches be easily applied and maintained, so that people can test your code, and it can be easily merged into CVS once tested. Here are some suggestions:

  • Patches should be made against a current, clean CVS checkout.
  • Patches should be made recursively against the full CVS module that it patches.
    • For instance, a patch that affects asterisk/apps/app_queues, and several files in asterisk/sound should be made against the whole asterisk/ tree.
  • Patches should be made with 'diff -Naur OLD.dir NEW.dir'

So, in the above example:

diff -Naur asterisk.old asterisk.new > asterisk-my_descriptive_patch_name-my.patch.version.patch


Assuming that a user has their Asterisk source in /usr/src, this would be applied by:

cp asterisk-my_descriptive_patch_name-my.patch.version.patch /usr/src
cd /usr/src/asterisk
patch -p1 <../asterisk-my_descriptive_patch_name-my.patch.version.patch


Coding Guidelines

NB For the latest info on this, check the file doc/CODING-GUIDELINES in the distribution

  • All code, filenames, function names and comments must be in ENGLISH.

  • Do not declare variables mid-function (e.g. like GNU lets you) since it is harder to read and not portable to GCC 2.95 and others.

  • Don't annotate your changes with comments like "/* JMG 4/20/04 */";

  • Comments should explain what the code does, not when something was changed or who changed it.

  • Don't make unnecessary whitespace changes throughout the code.

  • Don't use C++ type (//) comments.

  • Try to match the existing formatting of the file you are working on.

  • Functions and variables that are not intended to be global must be declared static.

  • Function calls and arguments should be spaced in a consistent way across the codebase.

Function Calls



GOOD: foo(arg1, arg2);
GOOD: foo(arg1,arg2);	/* Acceptable but not preferred */
BAD: foo (arg1, arg2);
BAD: foo( arg1, arg2 );
BAD: foo(arg1, arg2,arg3);


Examples of how code should be formatted



Functions


int foo(int a, char *s)
{
	return 0;
}


If statements


if (foo) {
	bar();
} else {
	blah();
}


Case statements


switch (foo) {
	case BAR:
		blah();
		break;
	case OTHER:
		other();
		break;
}


No nested statements without braces

e.g. no:

for (x=0;x<5;x++)
        if (foo) 
                if (bar)
                        baz();


instead do:

for (x=0;x<5;x++) {
        if (foo) {
                if (bar)
                        baz();
        }
}


Created by: jpiterak, Last modification: Sun 11 of Sep, 2005 (12:37 UTC) by atif
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+