Coding Style
If you intend to submit patches to PJSIP, please be informed that we do have the following coding style in place. Please do not see this as something that we guard religiously, but it’s just the convention that has been established for the past couple of decades in the existing hundreds of thousand lines of code and we think it’s just nice if new codes could follow these conventions.
Space indentation
Indent by 4 characters and use spaces only.
The PJSIP distribution includes an .editorconfig file to set indentation to 4 spaces. Check https://editorconfig.org/ to see if your editor supports it or if a plugin needs to be downloaded.
Note
PJSIP indentation scheme was changed to use spaces only since version 2.13.
Limit line length
We usually limit the line length to 80 characters, especially in the header files.
A few violations in the .c
file are usually tolerated, especially in the test files
where the audience is limited, but usually they are less than 90 characters too.
Use ANSI C/C90 Standard
Our code is ANSI C (a.k.a C89, C90, ISO C) plus allowing C++ //
style comment for special
occasion (see next section). In some compilers this is called gnu89
, and
in gcc you can activate this with -std=gnu99
option.
Use C style comment
Use C style comment. We only use C++ //
style comment when we want some part of
disabled code to draw more attention than normal comment, and as a reminder in the
future that we used to have that code (and it was disabled for a reason). For example:
/* Everything is fine, this is just a normal comment */
i += 1;
// This code is suspicious, I'm disabling it until further investigation
// *(int*)0 = 0;
No declaration after statement
We don’t use declaration after statement because our compiler did not support it back then (even Visual Studio 2005 still did not support it) and this is not allowed by C90 (or so we thought).
Note
But somewhat it is allowed by current gcc -std=c90
and gcc -std=gnu89
,
though you can get gcc to warn you about it with -Wdeclaration-after-statement
.
We would appreciate if you could avoid it too.
Use Doxygen comments for API
All public API in header files must be documented in Doxygen format. This includes structs, enums, and their members, functions, their arguments, macros, etc.
Please see example in the next section on how to indent the comments.
Use K&R style brace placement
Braces are on their own lines for struct, enum, and function definitions:
/** Doxygen comment */
typedef struct some_type
{
/** Doxygen comment */
int member_a;
/** Doxygen comment */
char member_b;
} some_type;
/** Doxygen comment */
enum some_constant_t
{
/** Doxygen comment */
CONSTANT_1,
/** Doxygen comment */
CONSTANT_2;
};
/**
* Doxygen comment describing the function.
*
* @param a First parameter
* @param b Second parameter, same indentation as other params.
*
* @return Zero on success or ..., indentation aligned with above too.
*/
int my_func(int a, int b)
{
return 0;
}
For other blocks, opening braces are on the same line, except if the statement preceeding the braces is multiline
for (i=0; i<count; ++i) {
...
}
/* multiline example */
while (imagine_long_expression_here > 0 &&
another_condition_is_true)
{
}
Multiline function arguments
Parameters should be aligned when they are broken into multiple lines, like this:
PJ_DECL(void) pj_array_insert(void *array,
unsigned elem_size,
unsigned count,
...);
instead of this:
PJ_DECL(void) pj_array_insert(void *array,
unsigned elem_size,
unsigned count,
...);
Multiline comment indentation
Multiline comments should be indented neatly.
For doxygen documentation, should be like this:
/**
* First line describing the function.
* Second line describing the function.
*/
And not like this:
/** First line describing the function.
* Second line describing the function.
* Alas, they don't align!
*/
For multiline comments in the code, should be like this:
/* First line describing something.
* Second line describing the something.
*/
And not like this:
/* First line describing something.
* Second line describing the something.
* Alas, they don't align!
*/
Please observe existing code
Those are the main things about coding style that we wish new code would follow. This document will be too terse if we have to mention all the little bits about style. For everything else, please observe existing codes and adjust the style accordingly.