Ne10 Coding Style

Joe Savage edited this page Nov 9, 2016 · 1 revision

Though Ne10 does not enforce code style particularly strictly, there are some rough syntactic rules and semantic suggestions which we encourage contributors to follow in order to maintain some consistency within the codebase. Failing to abide to the more important parts of these guidelines — for example, by indenting your code with two spaces — wastes code reviewers' time, and will likely result in having to spend more time correcting the code than it would have taken to simply write it properly in the first place!

General guidelines

  • Filenames should be in lowercase, with the uppercase prefix "NE10"
  • Header files should use the .h file extension
  • Implementation files should use one of the following file extensions: .c, .cpp, .s, .S
    • The lowercase .s extension is for raw assembly, while the uppercase .S is for assembly that is first preprocessed
  • Every file should include the standard Ne10 license comment at the start
  • Spaces should be used for indentation rather than tabs (language specifics are outlined below)
  • Lines should not be much longer than ~100 characters
  • Only English should be used in comments and string literals
  • The code style within a file should be kept internally consistent where possible
  • Where it does not result in a performance degradation, readable code is preferred to pre-optimised code
  • The relevant doxygen documentation and comments should be updated when changes are made

C

Ne10 roughly follows the C coding style used in the Linux kernel, with a few notable exceptions, including:

  • Four spaces are used for indentation
  • Braces are always placed on separate lines
  • Spacing is put around the “outside” of parentheses in function calls
  • Single line comments are A-OK

Some examples of the style of C code used within the project follow.

/**
 * @brief This function does X, Y, Z (this is a function description doxygen comment)
 * @param[in]   arg              a short description of the `arg` parameter
 * @return                       a short description of the return value
 *
 * This is a longer description of the function, detailing its nuances and intricacies,
 * of which it may have a great number.
 */
void some_function (int arg)
{
    int i; // This is a comment

    /* This is also a comment */
    return 0;
}
if (a > 5)
{
    some_function_call (params);
}
else if (abs (a) < 5)
{
    const int *ptr = b; // We prefer "const int *" to "int const *" here
    if (!b)
    {
        while (some_condition)
        {
            ptr++;
        }
    }
    return ptr;
}
else
{
    // Do something
}
#define FOO
#define NE10_ADD1(X) ((X) + 1)
#define NE10_CPX_ADD(Z,A,B) \
    do { \
        Z.r = A.r + B.r; \
        Z.i = A.i + B.i; \
    } while (0)

Assembly

The format of assembly files is less consistent within the project, but each should use an internally consistent formatting style. Currently, the assembly files used within Ne10 roughly abide to the following recommended format:

  • Multi-line comments are preferred over single-line comments
  • After the license comment is a file description comment which is not indented
  • Function description comments are indented by eight spaces
  • Directives are in lowercase and are indented by eight spaces
  • Macro names are in uppercase
  • Register aliases are in lowercase
  • Instructions are in lowercase, and are indented by eight spaces
  • Labels are in lowercase (using underscores where necessary)
  • Labels have a single blank line preceding them, are not indented

An example snippet of assembly code with this format follows.

/*
 * Copyright <snip> (license comment)
 */

/*
 * File description comment
 *
 * This provides some information about the file.
 */

        .text
        .syntax unified

        /**
         * Function description comment (can use doxygen syntax like in C)
         */

        .align 4
        .global
        .thumb
        .thumb_func
        .equ BITS, 0x16

ne10_function_name_neon:
        push { r4-r6, lr }

        /* A regular comment */
        src .req r0
        beta .req r1

        d_beta0 .dn d0

        ldr             beta, [src]
        vmov.s32        d_beta0, beta

some_label:
        /* Return from function */
        pop     { r4-r6, pc }

        .unreq src
        .unreq beta

        .unreq d_beta0
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.