[Freeipa-devel] Suggested additions to codding standard page on freeIPA wiki.

[John Dennis]

I'm going to respond to each persons email seperately, but only where I 
have something to add.

Simo Sorce wrote:
> Global variables should be discouraged as well, they make for very poor
> code. Should be used only if no other way can be found. They tend to be
> not thread/async safe
>   
+1
>   
>> * Declarations of external functions
>>     
>
> Should not be needed, usually headers should contain foreign functions
> definitions.
>
>   
+1
>> * Declarations of static functions
>>     
>
> I find it much easier to declare functions only if they need to be
> referenced before the body of the function is defined. Otherwise just
> use the ordering in the file to avoid declarations.
>
>   
-1

All functions should have prototypes declared at the top of the file. 
Depending on ordering is a side effect, side effects are to be avoided 
because of unintended consequences. Examples of non-obvious problems 
caused by this is reordering functions in a file or needing to call a 
function closer to the top of the file than was the case previously. 
It's just safer to always have a declared prototype for everything.
>
>> It is not required but recommended to group and position functions in 
>> the module so that it is easier to understand.
>>     
>
> This is very controversial, for me easier to understand is when the
> innermost function is first in the file and the outermost is last, but
> for some that seem an unnatural bottom to top ordering.
>
>   
You can't make a rule about stuff like this, rather just use your 
experience so the result is something readable to yourself and others.
>
>> Do not use Hungarian notation (prefixing variable with the type). The 
>> only exception to the rule is pointers. The following example 
>> illustrates the case:
>>
>> void function_that_does_something(data_set inventory) {
>> int number_items =0;
>>
>> err=get_number_of_items_in_set(inventory, number_items);
>> ...
>> }
>>
>> int get_number_of_items_in_set(data_set inventory, int* p_number_items) {
>> ...
>> }
>>     
>
> This definition is redundant, int * already defines the variable as pointer.
> Please let's avoid the insane Hungarian Notation completely.
>
>   
+1

Hungarian notation is a scourge. I have some sympathy for using a 'p' 
prefix for pointers in some limited circumstances where confusion might 
arise, use your judgement.
> Function definitions:
>
> Always define a function on one line with the opening parenthesis on the
> next line.
> Example:
> struct foobar *foo_bar_fn(int foo, int bar)
> {
>
> Do not put the "{" on the same line or the return type on a previous
> line like.
>
> Example of NOT ok declaration:
> struct foobar *
> foo_bar_fn(int foo, int bar) {
>
> if the function declaration does not fit 80 chars, put arguments after
> the first on following lines and indent them to start after the "("
>
> Example:
> int very_long_function_name_that_makes_arguments_not_fit_80(int foo,
>                                                             int bar)
> {
>
>   
-1

I agree with Martin, the qualifiers and return type go on one line so 
that the function name can begin on the next line. It's way easier to 
visually spot function names when they begin on a line and some source 
code tools work better with this convention.
> Do not put spaces before or after parenthesis:
>
> OK:  int foo(int bar, int baz);
> NOT OK: bad ( arg1 , arg2 );
>
>   
+1
> Avoid complex variable initializations (like calling functions) when
> declaring variables like:
>
> 	int foobar = get_foobar(baz);
>
> but split it in:
> 	int foobar;
>
> 	foobar = get_foobar(baz);
>
>   
+1

-- 
John Dennis <jdennis at redhat.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20081101/17f09b13/attachment.htm>