Extremely Important Things We All Must Do

• For variable and function names use camel case, lower case starting names, e.g. myVariable, veryLongVariableNameIndeed, miracleFunction().
  Exception: (related to the next rule) Linux kernel code typically uses lower case, underscored variable names. For consistency sake, use that style when writing Linux kernel code.

• When in Rome, do as the Romans do. That is, when editing someone else's code who has a different style than yours, please neatly copy his style. It is no fun coming home and finding your furniture rearranged.

• Don't make any line in a source code longer than 80 characters. When you indent, do so cleanly, e.g.

void someFunc(void)
{
   if (   myNameIsGeorge()  &&   todayIsSunday()    && 
        (!itIsRaining()     ||   myUmbrellaWorks()) &&
          lawnNeedsCutting() )
   {
      cutGrassNow();
   }
}

• Whenever you make a change in a source file, especially one which you typically don't work on, you must put a brief comment with your initials and date before it. Also include a memorable description of what the change fixes which matches closely with your Perforce check-in comments. For big additions, also put a closing comment after your code, e.g.

void someFunc(void)
{
   oldCode();
   moreOldCode();

   // 10/12/00 MSW: added code to make the UI refresh properly.
   mattAddedCode();
   ...
   // 10/12/00 MSW: end changes

   yetMoreOldCode();
}

• Braces: ALWAYS use braces EVEN for one line clauses. Not doing so inevitably leads to errors when adding additional lines to the clause. Beyond that, use your favorite style except when it conflicts with the 'When in Rome' policy. For example...
  

      if (value)
      {    call_func ();
      }
      else 
      {    while (do_something()) {}
      }

      if (value) 
        call_func ();
      else
        while (do_something ());

• NEVER rely on NULL to be logically false. See WhatIsNULL for details.

  char *pc;
  ...
  if (pc == NULL)
  {
    ... 
  }

        
  char *pc;
  ...
  if (pc)        
  {
     ...
  }

• Test your code. Make sure you have at least 70% code path coverage before checking in any new code. If you are maintaining and modifying old code, ensure that you have 100% code coverage for the new code before checking in. By checking your code in to the SCM system you are attesting that not only is it Good Code, but its Working Code.

• All externally visible identifiers (ie visible by customers and other users) should have a nu?_ prefix, where the '?' is replaced by a letter signifying the aspect to which this identifier is related. eg:
  • nuD_identifier -- driver/kernel reated
  • nuC_identifier -- RLD controller related
  • nuF_identifier -- firmware core related
  • etc.

Very Good Strongly Encouraged Things to Do

• Pick smart variable names. There is an art to this. Here are some guidelines.
  • Note that regular use of // comments allows blocks of code to be easily and safely commented out during testing and development:
  • Spell it out. Don't be shy to use a nice, long name.
  • Besides inconsequential variables, pick names as if you knew you had to grep for them. So, the variable name shouldn't be one that would be found within any other variable name. For instance, except when their scope lasts only for a handful of lines, len, buf, ptr, and most of all, id are terrible names. Good names include things like rldTestButton, funkyTimingShim. Have fun.
  • By consistently using good descriptive names for important variables, and quick variable names for loops and temporary variables, it becomes very easy to look at a variable and say 'ok, this is just a temp variable I won't find scattered elsewhere about the code'.

• If you have trouble with pointers, see: CPointerHelp

• Keep function blocks small. It is a wonderful thing if it vertically and horizontally fits on one page.

• Ideally, have only 1 return statement per function. Sometimes this rule gets in the way, e.g.

int doSomething(int withThis)
{
   if (withThis < MAGIC_CONSTANT)
   {   return -1;
   }

   int checkThis = someNecessaryCodeForNextStep();
   if (checkThis > OTHER_MAGIC_CONSTANT)
   {   return -1;
   }
   
   int result;
   doNextThing();
   ...
   // remainder of a very long function body, where many
   //  complex and strange things happen to 'result'

   return result;
}

        
int doSomething(int withThis)
{
   int result;
   if (withThis < MAGIC_CONSTANT)
   {   result = -1;
   }
   else 
   {   int checkThis = someNecessaryCodeForNextStep();
       if (checkThis > OTHER_MAGIC_CONSTANT)
       {   result = -1;
       }
       else
       {   doNextThing();
           ...
           // remainder of a very long function body, where many
           //  complex and strange things happen to 'result'
       }
   }
   return result;
}

-- MattWalsh - 12 Oct 2000

  for (...; ...; ...) { /* Single spaces after ';'s 
   if (...) { // Single space before all open parens 
      call_afunc (arg1, arg2); // Single space after every argument 
      ac_line[10] = 'a'; // No space before subscripts 
      value = number * size + fudge; // Spaces around all operators 
    }
    else if (...){ // Don't nest the 'if' in the 'else' 
      value ++; // Always brace single line blocks for consistancy 
    }
    else { // for comments after code, only one space before comment 
      ... // Two char indent -- use spaces not TABs 
    }

    switch (value) {
      case 1:
        break; // Don't fall thru on cases -- do it all in one if possible
      case 2:
        code (); // If you must fall thru a case, document it
        // FALLING THROUGH!
      case 3:
        more_code ();
        break;
      case 4:
        break; // Indent cases as if they were blocks
      case 5: {
        this ();
        break;
      } // It is often useful to create a local context for a case
      default: { // Always have a default
        break;
      }
    }
  }

-- TWikiGuest - 07 Dec 2001