Coding style ============ File format ----------- Use `misc/lv_templ.c `__ and `misc/lv_templ.h `__ Naming conventions ------------------ - Words are separated by '\_' - In variable and function names use only lower case letters (e.g. *height_tmp*) - In enums and defines use only upper case letters (e.g. *e.g. MAX_LINE_NUM*) - Global names (API): - start with *lv* - followed by module name: *btn*, *label*, *style* etc. - followed by the action (for functions): *set*, *get*, *refr* etc. - closed with the subject: *name*, *size*, *state* etc. - Typedefs - prefer ``typedef struct`` and ``typedef enum`` instead of ``struct name`` and ``enum name`` - always end ``typedef struct`` and ``typedef enum`` type names with ``_t`` - Abbreviations: - Only words longer or equal than 6 characters can be abbreviated. - Abbreviate only if it makes the word at least half as long - Use only very straightforward and well-known abbreviations (e.g. pos: position, def: default, btn: button) Coding guide ------------ - Functions: - Try to write function shorter than is 50 lines - Always shorter than 200 lines (except very straightforwards) - Variables: - One line, one declaration (BAD: char x, y;) - Use ```` (*uint8_t*, *int32_t* etc) - Declare variables where needed (not all at function start) - Use the smallest required scope - Variables in a file (outside functions) are always *static* - Do not use global variables (use functions to set/get static variables) Comments -------- Before every function have a comment like this: .. code:: c /** * Return with the screen of an object * @param obj pointer to an object * @return pointer to a screen */ lv_obj_t * lv_obj_get_scr(lv_obj_t * obj); Always use ``/*Something*/`` format and NOT ``//Something`` Write readable code to avoid descriptive comments like: ``x++; /*Add 1 to x*/``. The code should show clearly what you are doing. You should write **why** have you done this: ``x++; /*Because of closing '\0' of the string*/`` Short "code summaries" of a few lines are accepted. E.g. ``/*Calculate the new coordinates*/`` In comments use \` \` when referring to a variable. E.g. :literal:`/\*Update the value of \`x_act`*/` Formatting ---------- Here is example to show bracket placing and using of white spaces: .. code:: c /** * Set a new text for a label. Memory will be allocated to store the text by the label. * @param label pointer to a label object * @param text '\0' terminated character string. NULL to refresh with the current text. */ void lv_label_set_text(lv_obj_t * label, const char * text) { /*Main brackets of functions in new line*/ if(label == NULL) return; /*No bracket only if the command is inline with the if statement*/ lv_obj_inv(label); lv_label_ext_t * ext = lv_obj_get_ext(label); /*Comment before a section*/ if(text == ext->txt || text == NULL) { /*Bracket of statements start inline*/ lv_label_refr_text(label); return; } ... } Use 4 spaces indentation instead of tab. You can use **astyle** to format the code. Run ``code-format.py`` from the ``scripts`` folder. pre-commit ---------- `pre-commit `__ is a multi-language package manager for pre-commit hooks. See the `installation guide `__ to get pre-commit python package installed into your development machine. Once you have ``pre-commit`` installed you will need to `set up the git hook scripts `__ with: .. code:: console pre-commit install now ``pre-commit`` will run automatically on ``git commit``! Hooks ----- The ``format-source`` local hook (see ``.pre-commit-config.yaml``) runs **astyle** on all the staged source and header files (that are not excluded, see ``exclude`` key of the hook configuration) before entering the commit message, if any file gets formatted by **astyle** you will need to add the change to the staging area and run ``git commit`` again. The ``trailing-whitespace`` hook fixes trailing whitespaces on all of the files. Skipping hooks -------------- If you want to skip any particular hook you can do so with: .. code:: console SKIP=name-of-the-hook git commit Testing hooks ------------- It's no necessary to do a commit to test the hooks, you can test hooks by adding the files into the staging area and run: .. code:: console pre-commit run name-of-the-hook