Skip to content

Latest commit

 

History

History
85 lines (75 loc) · 3.84 KB

CONTRIBUTING.md

File metadata and controls

85 lines (75 loc) · 3.84 KB
Raw

How to Contribute

Thank you for your interest in this library. I do appreciate any constructive comments or suggestions about this library. If you would like to contribute code, please do the following for non-trivial changes:

  1. Create an issue or send me an email so that I have some advance warning on what you would like to change.
  2. Please rebase your branch off the 'develop' branch, and preferably squash all your changes into a single commit so that it's easier to review.

Coding Style

I use the following style for this library. New code should follow the same style for consistency and ease of diffing.

  • formatting
    • 80 column lines
      • rationale: I often use vertically split, side-by-side editing on my small laptop screen.
    • 2 space indents, no tabs
    • 4 space indents for continuation lines
    • no trailing white spaces
  • spacing
    • consistent and generous spaces around operators and symbols
      • e.g. for (int i = 0; i < 10; i++) {
      • e.g. a = (flag) ? 3 : -1;
      • rationale: Helps readability.
    • space after language keywords: e.g. for, while, if, etc
    • no space after function names
  • pointer declaration * attached to the class, not the variable
    • e.g. AceButton* button, not AceButton *button
    • rationale: I know the latter could be argued to be technically more correct under the C/C++ syntax, but I think the former is more intuitive for many people. I've personally gone back and forth, and I decided to just pick a style.
  • only one variable declaration per line
    • e.g. int i, j; not allowed, use 2 lines
    • rationale: Helps readability, and avoids the confusion of AceButton* b1, *b2; caused by the previous rule.
  • open brace on the same line as the function name (Java style)
  • naming conventions
    • class names: CamelCase
      • e.g. MyClass, YourClass
    • methods: camelCase
      • e.g. doSomething(), isCondition(), etc
      • rationale: Seems like the Arduino convention. Helps readability.
    • class static constants: 'k' followed by CamelCase
      • e.g. kSomeConstant
      • rationale: Prevents conflicts with #define macros which use the ALL_CAPS_MACRO pattern. Since AceButton is a library, I cannot predict which other libraries may be used by the end-user. If there is a macro conflict, I have no way to fix the problem.
      • in user-land codes, ALL_CAPS for constants would be ok because if there's a conflict, you can change it
    • member variables: 'm' followed by CamelCase
      • e.g. mSomeVariable
      • rationale: Many symbols beginning with a single or double underscore __ are reserved by the C language, C++ language, or their standard libraries. So I avoid them completely. One alternative is to append an underscore after the variable name. But this makes the -> and the . operators hard to read. The 'm' prefix seems consistent with the 'k' prefix for constants, and it's easy on the eyes.
    • global variables
      • there ought to be no global variables in this library
      • if there were any, the naming convention would be 'gCamelCase'
  • doxygen comments for all public and protected methods and constants
    • comments are recommended for private methods and variables as well, since private methods sometimes become protected or public

Unit Tests

Any non-trivial change should have a unit test. Even a seemingly trivial change can often use a unit test to prevent typos.

Make sure that all the unit tests under the tests directory pass. I had to split the unit tests into multiple *.ino files because they became too big to fit into the 32KB flash memory space of an Arduino board.

Authorship and License

I will assume that your code is licensed under the same MIT License as the rest of the library.