Next: About this document Up: NIL/PIL Coding Guidelines Previous: Strong Suggestions

Suggestions

Parameter and local variable declarations should be indented and lined up:



        public  void  function( parameter1,
                                parameter2 )
            char          parameter1[];
            roi_struct    *parameter2;
        {
            int       i;
            float     current_value;
            float     min, max, average;

            for( i = 0;  i < MAX_ROIS;  ++i )
            {
                ...
            }
        }

Try to avoid using the C ability to perform operations within evaluations:
UNDESIRABLE:



        if( x == c++ )
        {
            function();
        }

        if( (x = y) < threshold )
        {
            function();
        }

        a[i++] = 0;
This is more complicated for others to read, and can introduce bugs when modifying code. Similarly, do not overload for and while loops:
UNDESIRABLE:


        for( i = 0, j = n;  i < n;
             ++i, --j )
PREFERABLE:


        j = n;
        for( i = 0;  i < n;  ++i )
        {
            --j;
        }

Use your own judgement, and keep in mind that, in general, the priority is readability.

Use a 'for' loop only for loops that actually function as 'for' loops:
UNDESIRABLE:



        for( i = 0;  str[i] == 'k';  ++i )
        {
            ...
        }
PREFERABLE:


        i = 0;
        while( str[i] \!= 'k' )
        {
            ...

            ++i;
        }

For pointer parameters, use the appropriate choice of '*' or '[ ]' to indicate what the parameter represents:



        public  void  validate( list,
                                num_errors )
            int    list[];
            int    *num_errors;
        {
        }

In this case the first parameter represents an array of integers and the second parameter represents a pointer to a single integer, i.e., passed by reference.

Where efficiency is not an issue, treat arrays as arrays, i.e. array addressing is preferred over pointer addressing:
UNDESIRABLE:



          s = string;

          for( i = 0;  i < strlen( s ); ++i )
          {
              if( *s == 'a' )
              {
                  break;
              }
              ++s;
          }
PREFERABLE:


          s = string;

          for( i = 0;  i < strlen( s ); ++i )
          {
              if( s[i] == 'a' )
              {
                  break;
              }
          }
This is because in order to understand how the pointer version works, one must examine the code to determine the history of the variable 's'. In this case it is trivial, but it will not always be. Use judgement.



Next: About this document Up: NIL/PIL Coding Guidelines Previous: Strong Suggestions


neelin@bic.mni.mcgill.ca
Tue Mar 22 16:51:19 EST 1994