tools/docs/help/Coding-Style-Guideline.md

   1 Coding Style Guideline
   2 ======================
   3
   4 * [Coding Style Guideline for C](#coding-style-guideline-for-c)
   5   * Validated Struct
   6   * Header Files
   7   * Formatting
   8   * Naming
   9   * Comments
  10 * [Coding Style Guideline for Javascript](#coding-style-guideline-for-javascript)
  11   * Javascript Language Rules
  12   * Javascript Style Rules
  13     * Naming
  14     * Formatting
  15 * [Coding Style Guideline for Python](#coding-style-guideline-for-python)
  16
  17
  18 # Coding Style Guideline for C
  19
  20 Our coding style guideline is based on [google c++ coding standard](https://google.github.io/styleguide/cppguide.html),
  21 but modified due to some difference between C and C++.
  22 When this guideline is ambiguous, just follow the result of running `./tools/check_tidy.py`.
  23
  24 Here are `./tools/check_tidy.py` options:
  25 ```
  26 --autoedit: Automatically edit the detected clang format errors. No diffs will be displayed.
  27 ```
  28
  29 ## Validated Struct
  30 Use [Validated Struct](../devs/Inside-IoT.js-Validated-Struct.md) whenever possible, for encapsulation and validity check.
  31
  32 ## Header Files
  33
  34 ### #define guard
  35 Use #define guard in all header files. `<FILE>_H` format is recommended.
  36
  37     #ifndef FILE_H
  38     #define FILE_H
  39         ...
  40     #endif // FILE_H
  41
  42 ## Formatting
  43
  44 ### Line length
  45 maximum 80 characters in a line.
  46
  47 ### Indentation
  48 2 space indent at a time. Do not use a tab for indentation.
  49
  50 ### Vertical whitespace
  51 Add two blank lines between functions.
  52
  53 Otherwise minimize use of vertical whitespace.
  54
  55 This is more a principle than a rule: don't use blank lines when you don't have to. In particular, don't put more than two blank lines between functions, resist starting functions with a blank line, don't end functions with a blank line, and be discriminating with your use of blank lines inside functions.
  56
  57 ### Function call
  58 Write a function call all in a line if it fits. If not, break the line into multiple lines after assignment operator, or insert newline between parameters.
  59 Do not insert spaces after open paren and before close paren.
  60
  61     int value = foo(arg1, arg2, arg3);
  62
  63     int value =
  64         foo(arg1, arg2, arg3);
  65
  66     int value = foo(arg1, arg2,
  67                     arg3);
  68
  69 ### Function Declaration and Definition
  70 Use named parameters in function declaration.
  71
  72     return_type function_name(int, char); // not allowed
  73     return_type function_name(int arg1, char arg2); // Use this
  74
  75 Return type should be on the same line as function name and parameters if it fits. If not, break between them aligned with the first argument.
  76
  77     return_type function_name(int arg1,
  78                               char arg2);
  79
  80 If even first argument does not fit in a line, write it in a new line with 4 space indent.
  81
  82     return_type function_name(
  83         int arg1, char arg2);
  84
  85
  86 The open curly brace should be at the same line. The close curly brace should be either at the same line as its open curly brace or at new line.
  87
  88     return_type function_name(int arg1, char arg2) { };
  89     return_type function_name(int arg1, char arg2) {
  90       ...
  91     }
  92     return_type function_name(int arg1, char arg2)
  93     {  // not allowed
  94       ...
  95     }
  96
  97 ### Conditionals
  98 Use a space between the if and open brace. Open brace on the same line as the if.
  99
 100     if (condition) {
 101         ...
 102     }
 103
 104 Short conditional statements may be written without braces.
 105
 106     if (condition)
 107       do_something();
 108
 109 ### Loops and Switches
 110 Use a space between the switch and loops(for, while, do-while) and open brace. Open brace on the same line as the switch and loops.
 111
 112     while (condition) {
 113       ...
 114     }
 115
 116 Single loop body statement may be written without braces.
 117
 118     while (condition)
 119       do_something(); // ok
 120     for (condition)
 121       do_something(); // ok
 122
 123
 124 ## Naming
 125
 126 ### Type names
 127 Use lower cases and underscore for struct names, and add prefix `iotjs_` and suffix `_t`.
 128
 129     typedef struct {
 130       ...
 131     } iotjs_name_t;
 132
 133 ### Function names
 134 Use lower cases and underscore for function names.
 135
 136 For constructors, destructor, and methods of validated struct `iotjs_mystruct_t`, use names starting with `iotjs_mystruct_*`.
 137 Constructor function name should be either `iotjs_mystruct_create` or `iotjs_mystruct_initialize`,
 138 depending on whether the constructor returns the instance as return value, or the constructor just initializes the instance passed by parameter.
 139
 140 ```c
 141 typedef struct {
 142 } IOTJS_VALIDATED_STRUCT(iotjs_mystruct_t);
 143
 144 iotjs_mystruct_t iotjs_mystruct_create(); // Ok
 145 iotjs_mystruct_t* iotjs_mystruct_create(); // Ok
 146 void iotjs_mystruct_initialize(iotjs_mystruct_t*); // Ok
 147
 148 void iotjs_mystruct_destroy();
 149
 150 int iotjs_mystruct_method();
 151 ```
 152
 153 ### Variable names
 154 Use lower cases and underscore for variable names.
 155
 156     int lower_case_variable;
 157
 158
 159 ## Comments
 160
 161 ### Comment style
 162 Use either // or /* */ style comments. However, // style is much prefered.
 163
 164
 165
 166 # Coding Style Guideline for Javascript
 167
 168 This coding standard is based on [google javascript coding standard](https://google.github.io/styleguide/javascriptguide.xml)
 169
 170 ## Javascript Language Rules
 171
 172 ### var
 173 Always declare variable before use.
 174
 175 ### Semicolons
 176 Always use semicolons.
 177
 178 ### Function Declaration in blocks
 179 Do not declare functions within a block.
 180
 181 ### Wrapper objects of primitive types
 182 Do not use wrapper objects for primitive types.
 183
 184 ### with
 185 Do not use `with` statement.
 186
 187 ### Modifying prototypes of builtin objects
 188 Do not modify prototypes of builtin objects
 189
 190 ## Javascript Style Rules
 191
 192 ### Naming
 193 Use lowerCamelCase for varible names and function names.
 194
 195     var myFirstVariable;
 196     function myFirstFunction {
 197       ...
 198     }
 199
 200 Use UpperCamelCase for constructor names
 201
 202     function MyConstructorFunction(input) {
 203       this.variable = input;
 204       ...
 205     }
 206
 207 ### Formatting
 208 Follow C/C++ formatting above.
 209
 210
 211 # Coding Style Guideline For Python
 212
 213 The coding conventions for Python code follows [PEP 8 - Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/)