acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
CONTRIBUTING.md (3928B)
      1 # How to Contribute
      2 
      3 Thank you for your interest in this library. I do appreciate any constructive
      4 comments or suggestions about this library. If you would like to contribute
      5 code, please do the following for non-trivial changes:
      6 
      7 1. Create an [issue](https://github.com/bxparks/AceButton/issues) or send me
      8    an email so that I have some advance warning on what you would like to
      9    change.
     10 1. Please rebase your branch off the 'develop' branch, and preferably squash all
     11    your changes into a single commit so that it's easier to review.
     12 
     13 ## Coding Style
     14 
     15 I use the following style for this library. New code should follow the same
     16 style for consistency and ease of diffing.
     17 
     18 * formatting
     19   * 80 column lines
     20     * _rationale_: I often use vertically split, side-by-side editing on my
     21       small laptop screen.
     22   * 2 space indents, no tabs
     23   * 4 space indents for continuation lines
     24   * no trailing white spaces
     25 * spacing
     26   * consistent and generous spaces around operators and symbols
     27     * e.g. `for (int i = 0; i < 10; i++) {`
     28     * e.g. `a = (flag) ? 3 : -1;`
     29     * _rationale_: Helps readability.
     30   * space after language keywords: e.g. `for`, `while`, `if`, etc
     31   * no space after function names
     32 * pointer declaration `*` attached to the class, not the variable
     33   * e.g. `AceButton* button`, not `AceButton *button`
     34   * _rationale_: I know the latter could be argued to be technically more
     35     correct under the C/C++ syntax, but I think the former is more intuitive for
     36     many people. I've personally gone back and forth, and I decided to just pick
     37     a style.
     38 * only one variable declaration per line
     39   * e.g. `int i, j;` not allowed, use 2 lines
     40   * _rationale_: Helps readability, and avoids the confusion of
     41    `AceButton* b1, *b2;` caused by the previous rule.
     42 * open brace on the same line as the function name (Java style)
     43 * naming conventions
     44   * class names: CamelCase
     45     * e.g. `MyClass`, `YourClass`
     46   * methods: camelCase
     47     * e.g. `doSomething()`, `isCondition()`, etc
     48     * _rationale_: Seems like the Arduino convention. Helps readability.
     49   * class static constants: 'k' followed by CamelCase
     50     * e.g. `kSomeConstant`
     51     * _rationale_: Prevents conflicts with `#define` macros which use the
     52       `ALL_CAPS_MACRO` pattern. Since AceButton is a library, I cannot predict
     53       which other libraries may be used by the end-user. If there is a macro
     54       conflict, I have no way to fix the problem.
     55     * in user-land codes, `ALL_CAPS` for constants would be ok because if
     56       there's a conflict, you can change it
     57   * member variables: 'm' followed by CamelCase
     58     * e.g. `mSomeVariable`
     59     * _rationale_: Many symbols beginning with a single or double underscore
     60       `__` are reserved by the C language, C++ language, or their standard
     61       libraries. So I avoid them completely. One alternative is to append an
     62       underscore *after* the variable name. But this makes the `->` and the `.`
     63       operators hard to read. The 'm' prefix seems consistent with the 'k'
     64       prefix for constants, and it's easy on the eyes.
     65   * global variables
     66     * there ought to be no global variables in this library
     67     * if there were any, the naming convention would be 'gCamelCase'
     68 * [doxygen](http://www.doxygen.org) comments for all public and protected
     69   methods and constants
     70   * comments are recommended for private methods and variables as well, since
     71     private methods sometimes become protected or public
     72 
     73 ## Unit Tests
     74 
     75 Any non-trivial change should have a unit test. Even a seemingly
     76 trivial change can often use a unit test to prevent typos.
     77 
     78 Make sure that all the unit tests under the `tests` directory pass. I had to
     79 split the unit tests into multiple `*.ino` files because they became too big to
     80 fit into the 32KB flash memory space of an Arduino board.
     81 
     82 ## Authorship and License
     83 
     84 I will assume that your code is licensed under the same MIT License as
     85 the rest of the library.