1  * Coding Style
  2  
  3  General Guidlines:
  4  
  5  1. Don't try to write the most compact code possible but rather the most
  6     readable.
  7  
  8  2. Avoid goto's (not eliminate at the cost of readability and simplicity)
  9  
 10  3. No tabs expanded to spaces.
 11  
 12  ** Editor
 13  Any editor of your choise, avoid brainded, bloated or over-intelligent ones.
 14  
 15  braindead:
 16  
 17  notepad - dos line endings, seriously?.
 18  notepad++ - braindead++
 19  
 20  bloated:
 21  eclipse - need a server to run
 22  visualstudio - not now.
 23  
 24  over-intelligent:
 25  <oh many>
 26  
 27  vim configuration:
 28  
 29  
 30  indent command: 
 31  
 32  Indent comand related options are provided in indent-options
 33  file under 'tools' directory.
 34  
 35  
 36  ** Whitespace
 37  
 38  - Indents are four spaces.  
 39  - Tabs are never used, except in Makefiles (which dont exist anymore :) )
 40  
 41  - Do not leave whitespace dangling off the ends of lines.
 42   a.k.a Trailing whitespaces
 43  
 44  Whitespace around every operator
 45  #+BEGIN_SRC c
 46  if(c==0)
 47  // VS
 48  if (c == 0)
 49     //^//^
 50  #+END_SRC
 51  
 52  Whitespace after 'if' 'while' and 'for', 'switch'
 53  #+BEGIN_SRC c
 54  for (i = 0; i < 5; i++) {}
 55  // ^
 56  while () {
 57  } // ^
 58  
 59  do {
 60  //^
 61  while (cond) ;
 62    // ^
 63  
 64  if (cond)
 65  //^
 66  switch (case_val) {
 67  }
 68  #+END_SRC
 69  
 70  The paranthesis shold be on the same line in compound statements 'if', 'while'
 71  'for' and 'switch'
 72  #+BEGIN_SRC c
 73  while (cond) {
 74  }         // ^
 75  
 76  for (...) {
 77  }      // ^
 78  
 79  if (cond) {
 80  }      // ^
 81  
 82  switch (cond) {
 83  }          // ^
 84  #+END_SRC
 85  
 86  ** Alignment
 87  Switch - case, the 'case' statements aligned with switch.
 88  #+BEGIN_SRC c
 89  switch(something) {
 90  case 1:
 91  break;
 92  case 2:
 93  break;
 94  default:
 95  break;
 96  }
 97  #+END_SRC
 98  
 99  goto lables should be aligned on the column '1'.
100  #+BEGIN_SRC c
101    func () {
102        if (cond) {
103            print("error\n");
104            goto out;
105        }
106    out:
107        return 0;
108    }
109  #+END_SRC
110  
111  ** Line width
112  
113  Lines are 80 characters; not longer.
114  Do anything that takes to cut the long lines,
115  eg:
116  #+BEGIN_SRC c
117    if (condition_true)
118      struct libm_test *exp2_v2d = libm_test_alloc_init(conf, &exp2_test_template);
119  #+END_SRC
120  
121  Write instead like this
122  #+BEGIN_SRC c
123    struct libm_test *exp2_v2d;
124  
125    exp2_v2d = libm_test_alloc_init(conf, &exp2_test_template);
126  #+END_SRC
127  
128  
129  ** Naming
130  
131   - Variables are function names lower_case_with_underscores; easy to type and read.
132  eg:
133  #+BEGIN_SRC c
134     uint8_t *test_data;
135  #+END_SRC
136  
137   - Structured type names are in CamelCase; harder to type but standing out.
138  #+BEGIN_SRC c
139  LibmTestData *data;
140  LibmTest     *test;
141  #+END_SRC
142  
143   - enum or #defined constants should be Uppercase (or UPPER-CASE).
144  #+BEGIN_SRC c
145  #define DBG_BIT 1
146  
147  // And
148  
149  enum {
150  TEST_TYPE_ACCU
151  };
152  #+END_SRC
153   - Scalar type names are lower_case_with_underscores_ending_with_a_t,
154     like the POSIX uint64_t and family.
155  
156  When wrapping standard library functions, use the prefix amd_libm_ to alert
157  readers that they are seeing a wrapped version; otherwise avoid this prefix.
158  
159  ** Code
160  1. 
161  1. follow the standard idioms: use `x < 0' not `0 > x', etc.
162  2. don't write `!strcmp' (nor `!memcmp', etc.)  nor
163               `if(memcmp(a, b, c))'; always explicitly compare the
164               result of string or memory comparison with zero using a
165               relational operator.
166  #+BEGIN_SRC c
167  if (strncmp(c, "abcd", 5) == 0)
168  #+END_SRC
169  
170  
171  
172  ** Block structure
173  Avoid unwanted braces, though the following looks okay,
174  Example:
175  #+BEGIN_SRC c
176      if (a == 5) {
177          printf("a was 5.\n");
178      } else if (a == 6) {
179          printf("a was 6.\n");
180      } else {
181          printf("a was something else entirely.\n");
182      }
183  #+END_SRC
184  
185  Following looks better
186  #+BEGIN_SRC c
187    if (a == 5)
188        printf("a was 5.\n");
189    else if (a == 6)
190        printf("a was 6.\n");
191    else
192        printf("a was something else entirely.\n");
193  #+END_SRC
194  
195  Note that 'else if' is considered a single statement; otherwise a long if/
196  else if/else if/.../else sequence would need an indent for every else
197  statement.
198  
199  An exception is the opening brace for a function; for reasons of tradition
200  and clarity it will have a line for itself.
201  #+BEGIN_SRC c
202    void a_function(void)
203    {
204        do_something();
205    }
206  #+END_SRC
207  
208  Rationale: a consistent (except for functions...) bracing style reduces
209  ambiguity and avoids needless churn when lines are added or removed.
210  Furthermore, it is the QEMU coding style.
211  
212  ** Comments
213  - If your code is readable, you shouldn't need many comments. A line or two
214    comment above a function explaining what it does is always welcome.
215  
216  - Comment any code you find yourself wondering about for more than 2 seconds,
217    even if it's to say that you don't under- stand what's going on. Explain why.
218  
219  - Don't use commenting as an excuse for writing confusing code. Rewrite the code
220    to make it clear.