datapath-windows/CodingStyle

   1        Open vSwitch Windows Datapath Coding Style
   2        ==========================================
   3
   4 The coding style described in the Open vSwitch distribution gives the
   5 flexiblity for each platform to use its own coding style for the kernel
   6 datapath.  This file describes the specific coding style used in most
   7 of the C files in the Windows kernel datapath of the Open vSwitch distribution.
   8
   9 Most of the coding conventions applicable for the Open vSwitch distribution are
  10 applicable to the Windows kernel datapath as well.  There are some exceptions
  11 and new guidlines owing to the commonly followed practices in Windows
  12 kernel/driver code.  They are noted as follows:
  13
  14
  15 BASICS
  16
  17   Limit lines to 79 characters.  Many times, this is not possible due to long
  18 names of functions and it is fine to go beyond the characters limit.  One
  19 common example is when calling into NDIS functions.
  20
  21
  22 TYPES
  23   Use data types defined by Windows for most of the code.  This is a common
  24 practice in Windows driver code, and it makes integrating with the data
  25 structures and functions defined by Windows easier.  Example: DWORD and
  26 BOOLEAN.
  27
  28   Use caution in portions of the code that interface with the OVS userspace.
  29 OVS userspace does not use Windows specific data types, and when copying data
  30 back and forth between kernel and userspace, care should be exercised.
  31
  32
  33 NAMING
  34
  35   It is common practice to use camel casing for naming variables, functions
  36 and files in Windows.  For types, especially structures, unions and enums,
  37 using all upper case letters with words seprated by '_' is common. These
  38 practices can be used for OVS Windows datapath.  However, use the following
  39 guidelines:
  40
  41   Use lower case to begin the name of a variable.
  42
  43   Use upper case to begin the name of a function, enum, file name etc.
  44
  45   For types, use all upper case for all letters with words separated by '_'. If
  46   camel casing is preferred, use  upper case for the first letter.
  47
  48   It is a common practice to define a pointer type by prefixing the letter
  49 'P' to a data type.  The same practice can be followed here as well.
  50
  51   Example:
  52
  53 static __inline BOOLEAN
  54 OvsDetectTunnelRxPkt(POVS_FORWARDING_CONTEXT ovsFwdCtx,
  55                      POVS_FLOW_KEY flowKey)
  56 {
  57     POVS_VPORT_ENTRY tunnelVport = NULL;
  58
  59     if (!flowKey->ipKey.nwFrag &&
  60         flowKey->ipKey.nwProto == IPPROTO_UDP &&
  61         flowKey->ipKey.l4.tpDst == VXLAN_UDP_PORT_NBO) {
  62         tunnelVport = OvsGetTunnelVport(OVSWIN_VPORT_TYPE_VXLAN);
  63         ovsActionStats.rxVxlan++;
  64     }
  65
  66     if (tunnelVport) {
  67         ASSERT(ovsFwdCtx->tunnelRxNic == NULL);
  68         ovsFwdCtx->tunnelRxNic = tunnelVport;
  69         return TRUE;
  70     }
  71
  72     return FALSE;
  73 }
  74
  75
  76 COMMENTS
  77
  78   Comments should be written as full sentences that start with a
  79 capital letter and end with a period.  Putting two spaces between sentances is
  80 not necessary.
  81
  82   // can be used for comments as long as the comment is a single line comment.
  83 For block comments, use /* */ comments
  84
  85
  86 FUNCTIONS
  87
  88   Put the return type, function name, and the braces that surround the
  89 function's code on separate lines, all starting in column 0.
  90
  91   Before each function definition, write a comment that describes the
  92 function's purpose, including each parameter, the return value, and
  93 side effects.  References to argument names should be given in
  94 single-quotes, e.g. 'arg'.  The comment should not include the
  95 function name, nor need it follow any formal structure.  The comment
  96 does not need to describe how a function does its work, unless this
  97 information is needed to use the function correctly (this is often
  98 better done with comments *inside* the function).
  99
 100   Mention any side effects that the function has that are not obvious based on
 101 the name of the function or based on the workflow it is called from.
 102
 103   In the interest of keeping comments describing functions similar in
 104 structure, use the following template.
 105
 106 /*
 107  *----------------------------------------------------------------------------
 108  * Any description of the function, arguments, return types, assumptions and
 109  * side effects.
 110  *----------------------------------------------------------------------------
 111  */
 112
 113 SOURCE FILES
 114
 115   Each source file should state its license in a comment at the very
 116 top, followed by a comment explaining the purpose of the code that is
 117 in that file.  The comment should explain how the code in the file
 118 relates to code in other files.  The goal is to allow a programmer to
 119 quickly figure out where a given module fits into the larger system.
 120
 121   The first non-comment line in a .c source file should be:
 122
 123     #include <precomp.h>
 124
 125 #include directives should appear in the following order:
 126
 127     1. #include <precomp.h>
 128
 129     2. The module's own headers, if any.  Including this before any
 130        other header (besides <precomp.h>) ensures that the module's
 131        header file is self-contained (see HEADER FILES) below.
 132
 133     3. Standard C library headers and other system headers, preferably
 134        in alphabetical order.  (Occasionally one encounters a set of
 135        system headers that must be included in a particular order, in
 136        which case that order must take precedence.)
 137
 138     4. Open vSwitch headers, in alphabetical order.  Use "", not <>,
 139        to specify Open vSwitch header names.