Coding Standards

Coding Standards

WIP: to be discussed

Indentation

New blocks (or offsets in a multi-line statement) should be indented by 4 spaces.

No tabs should be used - programmers must ensure that tab generation is turned off in their editors; indentation must be made with spaces.

Bracketing

Curly brackets starting a new code block should appear on the same line as the code that starts the block.

Example:

if (a == b) {
    x++;
}

Commenting and Documentation

Comments

Appropriate comments should be used to make the code clear, particularly regarding complex regular expressions (that have justifiably earned a "write-only" reputation) and complex map expressions, etc.

Documentation

Qore uses doxygen for documentation, so technical documentation can be placed with the code being documented.

• Each function, class, method, or public attribute should include comments about its meaning and usage
• Return and parameter types must be declared and documented
• Side effects must be documented
• Exceptions must be documented

For example:

%new-style
%require-types
%strict-args
%enable-all-warnings

#! this function processes the string argument and returns an integer code giving the string's relevance to society and the string's ability to affect future society
/** @param str the string argument to evaluate

    @return an integer code giving the relevance and potential future societal impact of the string (0 = irrelevant, will not influence society, 99 = the most relevant, highly influential to the future)

    @throw RELEVANCE-OVERLOAD an error occurred evaluating the relevance of the given string

    The algorithm behind this function is highly sophisticated and subject to change.  It may use quantum calculations (even on classical computers) or other approaches to calculate the return value.

    This function can print a message to the console with certain values.
*/
int sub eval_string_relevance(string str) {
    switch (string) {
        case "ABC":
            return 50;
        case "Dolphin":
            throw "RELEVANCE-OVERLOAD", sprintf("unknown error evaluating the relevance of %y", str);
    }

    printf("something else: %y\n", str);
    return 20;
}

Parse Options

See Parse Options