1  = Coding Style
  2  
  3  This chapter describes the source code style preferred by the LinuxCNC team.
  4  
  5  == Do no harm
  6  
  7  When making small edits to code in a style different than the one
  8  described below, observe the local coding style. Rapid changes from one
  9  coding style to another decrease code readability.
 10  
 11  Never check in code after running “indent” on it. The whitespace
 12  changes introduced by indent make it more difficult to follow the
 13  revision history of the file.
 14  
 15  Do not use an editor that makes unneeded changes to whitespace (e.g.,
 16  which replaces 8 spaces with a tabstop on a line not otherwise
 17  modified, or word-wraps lines not otherwise modified)
 18  
 19  == Tab Stops
 20  
 21  A tab stop always corresponds to 8 spaces. Do not write code that
 22  displays correctly only with a differing tab stop setting.
 23  
 24  == Indentation
 25  
 26  Use 4 spaces per level of indentation. Combining 8 spaces into one tab
 27  is acceptable but not required.
 28  
 29  == Placing Braces
 30  
 31  Put the opening brace last on the line, and put the closing brace first:
 32  
 33  [source,c]
 34  ----
 35  if (x) {
 36      // do something appropriate
 37  }
 38  ----
 39  
 40  The closing brace is on a line of its own, except in the cases where
 41  it is followed by a continuation of the same statement, i.e. a 'while'
 42  in a do-statement or an 'else' in an if-statement, like this:
 43  
 44  [source,c]
 45  ----
 46  do {
 47      // something important
 48  } while (x > 0);
 49  ----
 50  
 51  and
 52  
 53  [source,c]
 54  ----
 55  if (x == y) {
 56      // do one thing
 57  } else if (x < y) {
 58      // do another thing
 59  } else {
 60      // do a third thing
 61  }
 62  ----
 63  
 64  This brace-placement also minimizes the number of empty (or almost
 65  empty) lines, which allows a greater amount of code or comments to be
 66  visible at once in a terminal of a fixed size.
 67  
 68  == Naming
 69  
 70  C is a Spartan language, and so should your naming be. Unlike Modula-2
 71  and Pascal programmers, C programmers do not use cute names like
 72  ThisVariableIsATemporaryCounter. A C programmer would call that
 73  variable 'tmp', which is much easier to write, and not the least more
 74  difficult to understand.
 75  
 76  However, descriptive names for global variables are a must. To call a
 77  global function 'foo' is a shooting offense.
 78  
 79  GLOBAL variables (to be used only if you *really*  need them) need to
 80  have descriptive names, as do global functions. If
 81  you have a function that counts the number of active users, you should
 82   call that 'count_active_users()' or similar, you should *not* call it
 83  'cntusr()'.
 84  
 85  Encoding the type of a function into the name (so-called Hungarian
 86  notation) is brain damaged - the compiler knows the types anyway and
 87  can check those, and it only confuses the programmer. No wonder
 88  Microsoft makes buggy programs.
 89  
 90  LOCAL variable names should be short, and to the point. If you have
 91  some random integer loop counter, it should probably be called 'i'.
 92  Calling it 'loop_counter' is non-productive, if there is no chance of
 93  it being misunderstood. Similarly, 'tmp' can be just about any type of
 94  variable that is used to hold a temporary value.
 95  
 96  If you are afraid to mix up your local variable names, you have
 97  another problem, which is called the function-growth-hormone-imbalance
 98  syndrome. See next chapter.
 99  
100  == Functions
101  
102  Functions should be short and sweet, and do just one thing. They
103  should fit on one or two screenfuls of text (the ISO/ANSI screen size
104  is 80x24, as we all know), and do one thing and do that well.
105  
106  The maximum length of a function is inversely proportional to the
107  complexity and indentation level of that function. So, if you have a
108  conceptually simple function that is just one long (but simple)
109  case-statement, where you have to do lots of small things for a lot of
110  different cases, it's OK to have a longer function.
111  
112  However, if you have a complex function, and you suspect that a
113  less-than-gifted first-year high-school student might not even
114  understand what the function is all about, you should adhere to the
115  maximum limits all the more closely. Use helper functions with
116  descriptive names (you can ask the compiler to in-line them if you
117  think it's performance-critical, and it will probably do a better job
118  of it that you would have done).
119  
120  Another measure of the function is the number of local variables. They
121  shouldn't exceed 5-10, or you're doing something wrong. Re-think the
122  function, and split it into smaller pieces. A human brain can generally
123  easily keep track of about 7 different things, anything more and it
124  gets confused. You know you're brilliant, but maybe you'd like to
125  understand what you did 2 weeks from now.
126  
127  == Commenting
128  
129  Comments are good, but there is also a danger of over-commenting.
130  NEVER try to explain HOW your code works in a comment: it's much better
131  to write the code so that the *working* is obvious, and it's a waste of
132  time to explain badly written code.
133  
134  Generally, you want your comments to tell WHAT your code does, not
135  HOW. A boxed comment describing the function, return value, and who
136  calls it placed above the body is good. Also, try to avoid putting
137  comments inside a function body: if the function is so complex that you
138  need to separately comment parts of it, you should probably re-read the
139  Functions section again. You can make small comments to note or warn
140  about something particularly clever (or ugly), but try to avoid excess.
141  Instead, put the comments at the head of the function, telling people
142  what it does, and possibly WHY it does it.
143  
144  If comments along the lines of /* Fix me */ are used, please, please,
145  say why something needs fixing. When a change has been made to the
146  affected portion of code, either remove the comment, or amend it to
147  indicate a change has been made and needs testing.
148  
149  == Shell Scripts & Makefiles 
150  
151  Not everyone has the same tools and packages installed. Some people
152  use vi, others emacs - A few even avoid having either package
153  installed, preferring a lightweight text editor such as nano or the one
154  built in to Midnight Commander.
155  
156  gawk versus mawk - Again, not everyone will have gawk installed, mawk
157  is nearly a tenth of the size and yet conforms to the Posix AWK
158  standard. If some obscure gawk specific command is needed that mawk
159  does not provide, than the script will break for some users. The same
160  would apply to mawk. In short, use the generic awk invocation in
161  preference to gawk or mawk.
162  
163  == C++ Conventions
164  
165  C++ coding styles are always likely to end up in heated debates (a bit
166  like the emacs versus vi arguments). One thing is certain however, a
167  common style used by everyone working on a project leads to uniform and
168  readable code.
169  
170  Naming conventions: Constants either from #defines or enumerations
171  should be in upper case through out. Rationale: Makes it easier to spot
172  compile time constants in the source code. e.g. EMC_MESSAGE_TYPE
173  
174  Classes and Namespaces should capitalize the first letter of each word
175  and avoid underscores. Rationale: Identifies classes, constructors and
176  destructors. e.g. GtkWidget
177  
178  Methods (or function names) should follow the C recommendations above
179  and should not include the class name. Rationale: Maintains a common
180  style across C and C++ sources. e.g. get_foo_bar()
181  
182  However, boolean methods are easier to read if they avoid underscores
183  and use an 'is' prefix (not to be confused with methods that manipulate
184  a boolean). Rationale: Identifies the return value as TRUE or FALSE and
185  nothing else. e.g. isOpen, isHomed
186  
187  Do NOT use 'Not' in a boolean name, it leads only leads to confusion
188  when doing logical tests. e.g. isNotOnLimit or is_not_on_limit are BAD.
189  
190  Variable names should avoid the use of upper case and underscores
191  except for local or private names. The use of global variables should
192  be avoided as much as possible. Rationale: Clarifies which are
193  variables and which are methods. Public: e.g. axislimit Private: e.g.
194  maxvelocity_
195  
196  Specific method naming conventions
197  
198  The terms get and set should be used where an attribute is accessed
199  directly. Rationale: Indicates the purpose of the function or method.
200  e.g. get_foo set_bar
201  
202  For methods involving boolean attributes, set & reset is preferred.
203  Rationale: As above. e.g. set_amp_enable reset_amp_fault
204  
205  Math intensive methods should use compute as a prefix. Rationale:
206  Shows that it is computationally intensive and will hog the CPU. e.g.
207  compute_PID
208  
209  Abbreviations in names should be avoided where possible - The
210  exception is for local variable names. Rationale: Clarity of code. e.g.
211  pointer is preferred over ptr compute is preferred over cmp compare is
212  again preferred over cmp.
213  
214  Enumerates and other constants can be prefixed by a common type name
215  e.g. enum COLOR { COLOR_RED, COLOR_BLUE };
216  
217  Excessive use of macros and defines should be avoided - Using simple
218  methods or functions is preferred. Rationale: Improves the debugging
219  process.
220  
221  Include Statements Header files must be included at the top of a
222  source file and not scattered throughout the body. They should be
223  sorted and grouped by their hierarchical position within the system
224  with the low level files included first. Include file paths should
225  NEVER be absolute - Use the compiler -I flag instead. Rationale:
226  Headers may not be in the same place on all systems.
227  
228  Pointers and references should have their reference symbol next to the
229  variable name rather than the type name. Rationale: Reduces confusion.
230  e.g. float *x or int &i
231  
232  Implicit tests for zero should not be used except for boolean
233  variables. e.g. if (spindle_speed != 0) NOT if (spindle_speed)
234  
235  Only loop control statements must be included in a for() construct.
236  e.g. sum = 0; for (i = 0; i < 10; i++) { sum += value[i]; }
237  
238  NOT for (i = 0, sum =0; i < 10; i++) sum += value[i];
239  
240  Likewise, executable statements in conditionals must be avoided. e.g.
241  if (fd = open(file_name) is bad.
242  
243  Complex conditional statements should be avoided - Introduce temporary
244  boolean variables instead.
245  
246  Parentheses should be used in plenty in mathematical expressions - Do
247  not rely on operator precedence when an extra parentheses would clarify
248  things.
249  
250  File names: C++ sources and headers use .cc and .hh extension. The use
251  of .c and .h are reserved for plain C. Headers are for class, method,
252  and structure declarations, not code (unless the functions are declared
253  inline).
254  
255  == Python coding standards
256  
257  Use the http://www.python.org/dev/peps/pep-0008/[PEP 8] style for
258  Python code.
259  
260  == Comp coding standards
261  
262  In the declaration portion of a .comp file, begin each declaration at
263  the first column. Insert extra blank lines when they help group related
264  items.
265  
266  In the code portion of a .comp file, follow normal C coding style.
267