.. _coding-style: Coding style ============ File template ------------- 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: *button*, *label*, *style* etc. - followed by the action (for functions): *set*, *get*, 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: - The following abbreviations are used and allowed: - ``dsc`` descriptor - ``param`` parameter - ``indev`` input device - ``anim`` animation - ``buf`` buffer - ``str`` string - ``min/max`` minimum/maximum - ``alloc`` allocate - ``ctrl`` control - ``pos`` position - Avoid adding new abbreviations Coding guide ------------ - Functions: - Write function with single responsibility - Make the functions ``static`` where possible - 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 in ``.h`` files 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_screen(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`*/` API Conventions ---------------------- To support the auto-generation of bindings, the LVGL C API must follow some coding conventions: - Use ``enum``\ s instead of macros. If inevitable to use ``define``\ s export them with :cpp:expr:`LV_EXPORT_CONST_INT(defined_value)` right after the ``define``. - In function arguments use ``type name[]`` declaration for array parameters instead of :cpp:expr:`type * name` - Use typed pointers instead of :cpp:expr:`void *` pointers - Widget constructor must follow the ``lv__create(lv_obj_t * parent)`` pattern. - Widget members function must start with ``lv_`` and should receive :cpp:expr:`lv_obj_t *` as first argument which is a pointer to widget object itself. - ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the first argument, and the prefix of the ``struct`` name should be used as the prefix of the function name too (e.g. :cpp:expr:`lv_display_set_default(lv_display_t * disp)`) - Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as "private". - Argument must be named in H files too. - Do not ``malloc`` into a static or global variables. Instead declare the variable in ``lv_global_t`` structure in ``lv_global.h`` and mark the variable with :cpp:expr:`(LV_GLOBAL_DEFAULT()->variable)` when it's used. - To register and use callbacks one of the following needs to be followed. - Pass a pointer to a ``struct`` as the first argument of both the registration function and the callback. That ``struct`` must contain ``void * user_data`` field. - The last argument of the registration function must be ``void * user_data`` and the same ``user_data`` needs to be passed as the last argument of the callback. To learn more refer to the documentation of `MicroPython `__. 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