docs/CODING_STYLE

   1 This document attempts to explain basic styles and guidelines for the IPFire
   2 network codebase. New code should conform to these standards. Of course every
   3 rules has an exception, but still this should be followed as closely as
   4 possible.
   5
   6 # Naming & Formatting Code
   7
   8 ## Whitespace
   9
  10 Tabs. No spaces at an end of a line.
  11
  12 ## Line Length
  13
  14 Lines should not be longer than 80 characters. 120 is definitely the hard limit.
  15
  16 ## Indentation
  17
  18 One tab.
  19
  20 ## Control Structures
  21
  22         if cmd ...; then
  23                 cmd ...
  24         fi
  25
  26         while cmd ...; do
  27                 cmd ...
  28         done
  29
  30         local i
  31         for i in 1 2 3; do
  32                 cmd ...
  33         done
  34
  35         case "${var}" in
  36                 1)
  37                         cmd ...
  38                         ;;
  39                 2)
  40                         cmd ...
  41                         ;;
  42         esac
  43
  44 ## Variables
  45
  46 Variables must be used with curly brackets: ${var}, NOT $var
  47
  48 Global variables should be ${UPPERCASE}. Local variables should be ${lowercase}.
  49
  50 ## Function Declarations
  51
  52         # This explains what the function is doing and
  53         # how it is supposed to be used...
  54         foo() {
  55                 local arg1=${1}
  56                 local arg2=${2}
  57
  58                 cmd ...
  59                 cmd ...
  60         }
  61
  62 Arguments must be parsed as early as possible to give them meaningful names
  63 instead of using ${1}, ${2}, ...
  64
  65 ## Functions Exit Codes
  66
  67 Functions must always return a clean error code out of EXIT_OK, EXIT_ERROR,
  68 EXIT_TRUE, EXIT_FALSE or others so that things are easily readable.
  69
  70 ## Assertions
  71
  72 assert() should be used to catch any errors at runtime as early as possible.
  73
  74 They should not used to catch any issues that the user needs to be informed of.
  75
  76 The developer cannot rely on the statement being executed since we might skip the
  77 executing of assertions when ever we need to.
  78
  79 ## Lists
  80
  81 Lists of anything should be alphabetically ordered as long as there is no other
  82 (i.e. better) reason to sort them otherwise. IPv6 is always first.
  83
  84 ## Logging & Error Messages
  85
  86 Error messages must be short and clear. No trailing full stops.
  87
  88 They should always be passive sentences and present tense.