granicus.if.org Git - esp-idf/blob - docs/style-guide.rst

   1 Espressif IoT Development Framework Style Guide
   2 ===============================================
   3
   4
   5 About this guide
   6 ----------------
   7
   8 Purpose of this style guide is to encourage use of common coding practices within the ESP-IDF.
   9
  10 Style guide is a set of rules which are aimed to help create readable, maintainable, and robust code. By writing code which looks the same way across the code base we help others read and comprehend the code. By using same conventions for spaces and newlines we reduce chances that future changes will produce huge unreadable diffs. By following common patterns for module structure and by using language features consistently we help others understand code behavior.
  11
  12 We try to keep rules simple enough, which means that they can not cover all potential cases. In some cases one has to bend these simple rules to achieve readability, maintainability, or robustness.
  13
  14 When doing modifications to third-party code used in ESP-IDF, follow the way that particular project is written. That will help propose useful changes for merging into upstream project.
  15
  16 C code formatting
  17 -----------------
  18
  19 Indentation
  20 ^^^^^^^^^^^
  21
  22 Use 4 spaces for each indentation level. Don't use tabs for indentation. Configure the editor to emit 4 spaces each time you press tab key.
  23
  24 Vertical space
  25 ^^^^^^^^^^^^^^
  26
  27 Place one empty line between functions. Don't begin or end a function with an empty line.
  28 ::
  29
  30     void function1()
  31     {
  32         do_one_thing();
  33         do_another_thing();
  34                                     // INCORRECT, don't place empty line here
  35     }
  36                                     // place empty line here
  37     void function2()
  38     {
  39                                     // INCORRECT, don't use an empty line here
  40         int var = 0;
  41         while (var < SOME_CONSTANT) {
  42             do_stuff(&var);
  43         }
  44     }
  45
  46 Horizontal space
  47 ^^^^^^^^^^^^^^^^
  48
  49 Always add single space after conditional and loop keywords::
  50
  51     if (condition) {    // correct
  52         // ...
  53     }
  54
  55     switch (n) {        // correct
  56         case 0:
  57             // ...
  58     }
  59
  60     for(int i = 0; i < CONST; ++i) {    // INCORRECT
  61         // ...
  62     }
  63
  64 Add single space around binary operators. No space is necessary for unary operators. It is okay to drop space around multiply and divide operators::
  65
  66     const int y = y0 + (x - x0) * (y1 - y0) / (x1 - x0);    // correct
  67
  68     const int y = y0 + (x - x0)*(y1 - y0)/(x1 - x0);        // also okay
  69
  70     int y_cur = -y;                                         // correct
  71     ++y_cur;
  72
  73     const int y = y0+(x-x0)*(y1-y0)/(x1-x0);                // INCORRECT
  74
  75
  76 No space is necessary around ``.`` and ``->`` operators.
  77
  78
  79 Sometimes adding horizontal space within a line can help make code more readable. For example, you can add space to align function arguments::
  80
  81     gpio_matrix_in(PIN_CAM_D6,   I2S0I_DATA_IN14_IDX, false);
  82     gpio_matrix_in(PIN_CAM_D7,   I2S0I_DATA_IN15_IDX, false);
  83     gpio_matrix_in(PIN_CAM_HREF, I2S0I_H_ENABLE_IDX,  false);
  84     gpio_matrix_in(PIN_CAM_PCLK, I2S0I_DATA_IN15_IDX, false);
  85
  86 Note however that if someone goes to add new line with a longer identifier as first argument (e.g.  ``PIN_CAM_VSYNC``), it will not fit. So other lines would have to be realigned, adding meaningless changes to the commit.
  87
  88 Therefore, use horizontal alignment sparingly, especially if you expect new lines to be added to the list later.
  89
  90 Never use TAB characters for horizontal alignment.
  91
  92 Never add trailing whitespace at the end of the line.
  93
  94
  95 Braces
  96 ^^^^^^
  97
  98 - Function definition should have a brace on a separate line::
  99
 100     // This is correct:
 101     void function(int arg)
 102     {
 103
 104     }
 105
 106     // NOT like this:
 107     void function(int arg) {
 108
 109     }
 110
 111 - Within a function, place opening brace on the same line with conditional and loop statements::
 112
 113     if (condition) {
 114         do_one();
 115     } else if (other_condition) {
 116         do_two();
 117     }
 118
 119
 120 Comments
 121 ^^^^^^^^
 122
 123 Use ``//`` for single line comments. For multi-line comments it is okay to use either ``//`` on each line or a ``/* */`` block.
 124
 125 Although not directly related to formatting, here are a few notes about using comments effectively.
 126
 127 - Don't use single comments to disable some functionality::
 128
 129     void init_something()
 130     {
 131         setup_dma();
 132         // load_resources();                // WHY is this thing commented, asks the reader?
 133         start_timer();
 134     }
 135
 136 - If some code is no longer required, remove it completely. If you need it you can always look it up in git history of this file. If you disable some call because of temporary reasons, with an intention to restore it in the future, add explanation on the adjacent line::
 137
 138     void init_something()
 139     {
 140         setup_dma();
 141         // TODO: we should load resources here, but loader is not fully integrated yet.
 142         // load_resources();
 143         start_timer();
 144     }
 145
 146 - Same goes for ``#if 0 ... #endif`` blocks. Remove code block completely if it is not used. Otherwise, add comment explaining why the block is disabled. Don't use ``#if 0 ... #endif`` or comments to store code snippets which you may need in the future.
 147
 148 - Don't add trivial comments about authorship and change date. You can always look up who modified any given line using git. E.g. this comment adds clutter to the code without adding any useful information::
 149
 150     void init_something()
 151     {
 152         setup_dma();
 153         // XXX add 2016-09-01
 154         init_dma_list();
 155         fill_dma_item(0);
 156         // end XXX add
 157         start_timer();
 158     }
 159
 160
 161 Formatting your code
 162 ^^^^^^^^^^^^^^^^^^^^
 163
 164 You can use ``astyle`` program to format your code according to the above recommendations.
 165
 166 If you are writing a file from scratch, or doing a complete rewrite, feel free to re-format the entire file. If you are changing a small portion of file, don't re-format the code you didn't change. This will help others when they review your changes.
 167
 168 To re-format a file, run::
 169
 170     tools/format.sh components/my_component/file.c
 171
 172 Documenting code
 173 ----------------
 174
 175 Please see the guide here: :doc:`documenting-code`.
 176
 177 Structure and naming
 178 --------------------
 179
 180
 181
 182 Language features
 183 -----------------
 184
 185 To be written.
 186