Loading...
 

Coding style

Intro

This page is to document the coding style for Qore and C++ as agreed upon on 2017/11/29.
Please observe the rules and/or speak up if any of the rules don't work in which case the rule will be revisited again and possibly changed if that will make sense.

Updating existing code

Only change existing code if it makes sense (it is not intended to spent days formatting old code base only to add few new lines).
Update style of existing files lazily, i.e. if you happen to need to modify (adding functionality, fixing bugs, etc.) an existing file and you find its style to be not in accordance with the current style, please fix the style first as a *separate commit* and only then make the functional changes you originally planned.

The style

Line length

Maximum of 120 characters.

Indentation

  • 4 spaces. No tabs. UNIX ends-of-lines.
  • No white chars at the end of lines
  • Line continuation - align with the first element on the same level (e.g. within the same parens) as on the previous line:
if (a == 1 ||
    b == 2) {
    throw "A-B-ERROR", sprintf("A: %y B: %y",
                               a, b),
          { "a": a, "b": b };
}

  • switch statements have 'case' indented:
switch (var) {
    case 1:
        do_for_one();
        break;
    default:
        do_default();
}

Braces

Braces are "java" style, i.e.:
class Cls {
	method() {
		if (...) {
			...
		} else if {
			...
		}
    }
}

If/for/foreach/while body is always enclosed in curly braces

Even if the body is just one line.
if (a) {
	return a;
} else {
	return b;
}

while (True) {
    burn_that_cpu();
}

Comments

  • Multiline comments are to be properly indented to the same level as the code they comment.
  • There should be no extra asterisks on the "inner" lines.
  • The content should be indented.
  • Align opening and closing asterisks
  • Single line comments both # or /* ... */
/*
    This is a really cool class and this is a dummy comment.
 */
class Cls {
    #! What a method! Brief description goes here.
    /**
      @param x    Param x descriptions, see @ allign with second *
      @return string  ....
     */
    string method(int x) {
        if (...) {
            ...
        } else if {
            ...
        }
        # Some cool logic here
        ...
    }
    /*
        Blah blah blah
        Lore ipsum ...
     */
}

Space padding / spaces

  • Pad operators
  • Pad commas
  • Pad header (i.e. _"Insert space padding between a header (e.g. 'if', 'for', 'while', 'catch' ...) and the following paren."_).
  • No padding in other cases than above, i.e. no padding between a function/method name and the first paren of its arguments.
if (isFoo((a + 2), b)) {
	bar(a, b);
}

List and hash literals

  • List literals are using parens, i.e. (1, 2, 3, ...)
  • Hash literals are using curly braces, i.e. {"a": 1, "b": 2}

astyle

We'll be using http://astyle.sourceforge.net/astyle.html to help us format (and check) the code.
Please note that there are currently outstanding issues with astyle that it doesn't work well with Qore multi-line strings. So please use with caution until further communication.
The configuration file .astylerc for the style as described here is as follows:
# switch to qore mode
--mode=qore

# basic indenting style
--style=java

# space based indenting with 4 spaces
--indent=spaces=4
--convert-tabs

# max line length - suggestion for astyle only
--max-code-length=120

# EOL setting
--lineend=linux

# unified comments - no newline with star in block comment
--remove-comment-prefix

# unified handling of braces and whitespace at all
--attach-inlines
--indent-classes
--break-blocks
--pad-oper
--pad-comma
--unpad-paren
--pad-header

# oneline if/else statements are covered by a block all the time
--add-braces