Coding Guide

This document describes the coding style used for the OS2AHCI driver.

General

• All source code derived from IBM DDK sources shall retain its original coding style. Exceptions may be allowed if it is determined that reformatting the source code will make it more easily maintained.

Note: at time of writing, OS2AHCI does not contain any code derived from IBM DDK sources.

• All code submitted to the AHCI subversion repository shall build without errors or warnings.
• All source code submitted to the Subversion repository shall build correctly on any system that has the required development tools installed, as defined in Building the AHCI Driver.
• All source code shall be written in English, including comments, function names and variables.
• All unmodified source code from the IBM DDK distribution shall retain the original IBM copyright notices.
• All source code derived from IBM source code shall retain the original IBM copyright notices and shall bear the following additional copyright notices

    Copyright (c) 2011 thi.guten Software Development
    Copyright (c) 2011 Mensys B.V.
  

• All other independently developed source code shall bear the copyright notices

    Copyright (c) 2011 thi.guten Software Development
    Copyright (c) 2011 Mensys B.V.
  

Coding Style

General

• Indentation is 2 spaces
• Tabs are not used, but if they slip in, tab width must be 8 chars
• line length does not exceed 80 characters
• Source file encoding is CP-437; no characters above '~' (0x7e) are used so the code is viewable/editable using most 8bit character sets

Function Definitions

• The opening brace of a function is put on a separate line; the function body is indented:

  void foo(void)
  {
    /* here comes the code */
  }
  

• old style function declarations (parameter types after the closing brace) are not used
• function parameters are put on one line; if the line exceeds 80 chars, a line break is inserted:

  void lots_of_args(char *parameter1_name, int integer_parm_name, 
                    float float_parm_name, HFILE file_handle)
  {
    ...
  }
  

• function definitions must be preceeded by a descriptive comment of the following form:

  /******************************************************************************
   * Description of the function. Description of the function. 
   * Description of the function. Description of the function. 
   *
   * NOTE: An optional note, it is optional.
   *       2nd note line is indented.
   */
  

Naming

• internal function and variable names are all lowercase, with underscores between words:

    int adapter_idx;
  

• structure type names and preprocessor constants are all uppercase:

  #define DEFAULT_ADAPTER_IDX   0
  typedef unsigned short ADAPTER_INDEX;
  

• simple types are all lowercase:

  typedef unsigned char    u8;
  

• preprocessor macros with arguments are all lowercase:

  #define spin_lock(sl)     DevHelp_AquireSpinLock(sl)
  

switch Statements

• switch statements are indented with case and switch on the same level, while each case block is indented one level, with an empty line between each case block:

    switch (iorb->CommandCode) {
  
    case IOCC_CONFIGURATION:
      iocc_configuration(iorb);
      break;
  
    default:
      break;
    }
  

• fall-through's in switch statements require a comment

code blocks

The following applies to all code blocks introduced by statements like if, while, do, for etc.

• blocks have the opening brace on the line of the opening statement:

  if (x == 0) {
    x = 1;
  }
  while (x < 0) {
    x++;
  }
  do {
    x++;
  } while (x < 0);
  

• the closing brace has the same indentation level as the opening statement
• if statements require braces:

  /* Good */
  if (c == 0) {
    c = 1;
  } else {
    c = 2;
  }
  
  /* not good: */
  if (c == 0)
    c = 1;
  else
    c = 2;
  
  /* evil: */
  if (x == 0) {
    /* lots of lines */
    ...
    ...
    ...
  } else
    printf("No no no!\n");
  
  

Comments

• C++ style single line comments are not used:

  // bad comment
  

• Very short comments may appear on the same line as the code they describe
• Multi line comments have a preceding star on each line:

  /* Complete initialization. From now on, we won't have to restore the BIOS
   * configuration after each command and we're fully operational (i.e. will
   * use interrupts, timers and context hooks instead of polling).
   */