1# Coding style
2
3## File format
4Use [misc/lv_templ.c](https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.c) and [misc/lv_templ.h](https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.h)
5
6## Naming conventions
7* Words are separated by '_'
8* In variable and function names use only lower case letters (e.g. *height_tmp*)
9* In enums and defines use only upper case letters (e.g. *e.g. MAX_LINE_NUM*)
10* Global names (API):
11  * start with *lv*
12  * followed by module name: *btn*, *label*, *style* etc.
13  * followed by the action (for functions): *set*, *get*, *refr* etc.
14  * closed with the subject: *name*, *size*, *state* etc.
15* Typedefs
16  * prefer `typedef struct` and `typedef enum` instead of  `struct name` and `enum name`
17  * always end `typedef struct` and `typedef enum` type names with `_t`
18* Abbreviations:
19  * Only words longer or equal than 6 characters can be abbreviated.
20  * Abbreviate only if it makes the word at least half as long
21  * Use only very straightforward and well-known abbreviations (e.g. pos: position, def: default, btn: button)
22
23## Coding guide
24* Functions:
25  * Try to write function shorter than is 50 lines
26  * Always shorter than 200 lines (except very straightforwards)
27* Variables:
28  * One line, one declaration (BAD: char x, y;)
29  * Use `<stdint.h>` (*uint8_t*, *int32_t* etc)
30  * Declare variables where needed (not all at function start)
31  * Use the smallest required scope
32  * Variables in a file (outside functions) are always *static*
33  * Do not use global variables (use functions to set/get static variables)
34
35## Comments
36Before every function have a comment like this:
37
38```c
39/**
40 * Return with the screen of an object
41 * @param obj pointer to an object
42 * @return pointer to a screen
43 */
44lv_obj_t * lv_obj_get_scr(lv_obj_t * obj);
45```
46
47Always use `/*Something*/` format and NOT `//Something`
48
49Write readable code to avoid descriptive comments like:
50`x++; /*Add 1 to x*/`.
51The code should show clearly what you are doing.
52
53You should write **why** have you done this:
54`x++; /*Because of closing '\0' of the string*/`
55
56Short "code summaries" of a few lines are accepted. E.g. `/*Calculate the new coordinates*/`
57
58In comments use \` \` when referring to a variable. E.g. ``/*Update the value of `x_act`*/``
59
60### Formatting
61Here is example to show bracket placing and using of white spaces:
62```c
63/**
64 * Set a new text for a label. Memory will be allocated to store the text by the label.
65 * @param label pointer to a label object
66 * @param text '\0' terminated character string. NULL to refresh with the current text.
67 */
68void lv_label_set_text(lv_obj_t * label, const char * text)
69{   /*Main brackets of functions in new line*/
70
71    if(label == NULL) return; /*No bracket only if the command is inline with the if statement*/
72
73    lv_obj_inv(label);
74
75    lv_label_ext_t * ext = lv_obj_get_ext(label);
76
77    /*Comment before a section*/
78    if(text == ext->txt || text == NULL) {  /*Bracket of statements start inline*/
79        lv_label_refr_text(label);
80        return;
81    }
82
83    ...
84}
85```
86
87Use 4 spaces indentation instead of tab.
88
89You can use **astyle** to format the code. Run `code-formatter.sh` from the `scrips` folder.
90