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