Fun to Program -- Coding style

Top

This was originally written and created around 2013 and may require to be updated. (2021)

Coding style

Follow the existing practice for the source.

Osamu’s preference at this moment is as follows:

For this document, 4 spaces as much as possible for any codes …
C and alike: normally Linux-style hardtab. (ts=8 noet)
Python: 4 spaces (The official indentation rule for Python, ts=4 sts=4 et)
Other scripts: also 4 spaces or hardtab. (ts=4 sts=4 et/ts=8 noet)
Lua: Language tutorial uses 2 spaces … but sometimes hardtab

C coding style

There are 2 major practices for the C coding style.

There are many variants in use.

K: Linux kernel coding style (system – K&R)
B: Busybox Style Guide (command line tool – K&R)
G: GTK+ Coding Style (GUI tool – GNU)

Here are summary of the K&R styles.

Keep it simple, Stupid! (KISS)
Indentation and line style
- Use tab for indentation.
  - K: Use “set tabstop=8 noexpandtab shiftwidth=8 textwidth=78” but do not use vi modeline in the code. (For more: http://www.jukie.net/bart/blog/vim-and-linux-coding-style)
  - B: Use vi modeline “vi: set sw=4 ts=4:” in the code.
- Opening brace is at the last on the line with a preceding space (except for function)
  - K: Do not unnecessarily use braces where a single statement will do.
  - B: Use braces even for a single statement. (The “bracketless” approach is error prone.)
  - “opening word” – “switch” – “case ...:” – “default:” – “}” in the same tabstop.
Space:
- No spaces used for indentation outside of comments and documentation.
- No spaces between function and its argument.
- No spaces between function like (pointer/address/type/size) operator and operand:
  - sizeof typeof alignof __attribute__ defined & * . ->
- No spaces between unary operators and its operand:
  - + - ~ ! ++ --
- No spaces (inside) parenthesized expressions.
- A space after (most) keywords:
  - if switch case for do while …
- A space around (most) binary and ternary operators:
  - = + - < > * / % | & ^ <= >= == != ? :
- No trailing whitespaces.
Names:
- GLOBAL variables: descriptive, lowercase with _, no encoding of type.
- LOCAL variables: short and to the point, lowercase.
- MACRO constants: all uppercase
K: Function code length should be 2 screens or less.
K: Comment on WHAT but never explain WHY with /* ... */
B: Comment before the logical block.
K: Functions return values:
- Action function: add_work()
  - => return error code integer: (non-zero = failure, 0 = success)
- Predicate function: pci_dev_present()
  - => return boolean: (0 = failure, non-zero = success)
Do not use pre-ANSI function declaration.

See also http://www.teamten.com/lawrence/style/notes.html[Notes on Programming Practices] by Lawrence Kesteloot for some detail C style examples.

Some style avoids the use of C99 style line comment preceded by “//” for compatibility.
Some style promotes the use of C99 style inline functions in C over macro.
Some style promotes the use of “enum { VAR = VALUE };” or C99 style “const <type> var = value;” over macro “#define VAR VALUE”.
GNU style uses GNU Coding Standards: Formatting Your Source Code which is significantly different from K&R such as indentation with 2 spaces etc.

Naming conventions

Basic naming convention used in C is:

normal identifiers: lowercase, lower_case, …
- integer temporary variables: i, j, k, m, n, …
- character temporary variables: c, d, e, …
- macro names: UPPERCASE, UPPER_CASE
system reserved identifiers: __???, _Uppercase, ???__, __???__, …

For many object oriented languages, CamelCase naming convention is introduced to differentiate between class name and class instance name.

class, interfaces, enums: UpperCamelCase
methods, local variables, fields:
- lowerCamelCase : Java, JavaScript, C++ (Google), …
- lower_case : Python, Ruby, Vala, Lua, …
constant: UPPER_CASE

The Hungarian Notation especially Systems Hungarian which encodes the physical data type into prefix is deplored. There are http://www.joelonsoftware.com/articles/Wrong.html[some defense to Apps Hungarian which encodes the logical data type into prefix].