acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
CODING_STYLE.md (4434B)
      1 # Coding style
      2 
      3 ## File format
      4 Use [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
     36 Before 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  */
     44 lv_obj_t * lv_obj_get_scr(lv_obj_t * obj);
     45 ```
     46 
     47 Always use `/*Something*/` format and NOT `//Something`
     48 
     49 Write readable code to avoid descriptive comments like:
     50 `x++; /*Add 1 to x*/`.
     51 The code should show clearly what you are doing.
     52 
     53 You should write **why** have you done this:
     54 `x++; /*Because of closing '\0' of the string*/`
     55 
     56 Short "code summaries" of a few lines are accepted. E.g. `/*Calculate the new coordinates*/`
     57 
     58 In comments use \` \` when referring to a variable. E.g. ``/*Update the value of `x_act`*/``
     59 
     60 ### Formatting
     61 Here 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  */
     68 void 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 
     87 Use 4 spaces indentation instead of tab.
     88 
     89 You can use **astyle** to format the code. Run `code-formatter.sh` from the `scrips` folder.
     90 
     91 #### pre-commit
     92 
     93 [pre-commit](https://pre-commit.com/) is a multi-language package manager for pre-commit hooks.
     94 See the [instalation guide](https://pre-commit.com/#installation) to get pre-commit python package
     95 installed into your development machine.
     96 
     97 Once you have `pre-commit` installed you will need to [set up the git hook scripts](https://pre-commit.com/#3-install-the-git-hook-scripts) with:
     98 ```console
     99 pre-commit install
    100 ```
    101 
    102 now `pre-commit` will run automatically on `git commit`!
    103 
    104 ##### Hooks
    105 
    106 The `format-source` local hook (see `.pre-commit-config.yaml`) runs **astyle** on all the staged source and header
    107 files (that are not excluded, see `exclude` key of the hook configuration) before entering the commit message,
    108 if any file gets formatted by **astyle** you will need to add the change to the staging area and run `git commit` again.
    109 
    110 The `trailing-whitespace` hook fixes trailing whitespaces on all of the files.
    111 
    112 ##### Skipping hooks
    113 
    114 If you want to skip any particular hook you can do so with:
    115 ```console
    116 SKIP=name-of-the-hook git commit
    117 ```
    118 
    119 ##### Testing hooks
    120 
    121 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:
    122 ```console
    123 pre-commit run name-of-the-hook
    124 ```