djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

CODECONVENTIONS.md: Update to reflect use of new tools/codeformat.py.

Browse Source
This commit is contained in:
Damien George 2020-02-28 12:35:19 +11:00
parent f6375ac3eb
commit 54a54f5872
1 changed files with 27 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
CODECONVENTIONS.md
View File

@ -11,7 +11,7 @@ It's also ok to drop file extensions.
Besides prefix, first line of a commit message should describe a Besides prefix, first line of a commit message should describe a
change clearly and to the point, and be a grammatical sentence with change clearly and to the point, and be a grammatical sentence with
final full stop. First line should fit within 78 characters. Examples final full stop. First line should fit within 72 characters. Examples
of good first line of commit messages: of good first line of commit messages:
py/objstr: Add splitlines() method. py/objstr: Add splitlines() method.
@ -19,9 +19,10 @@ of good first line of commit messages:
docs/machine: Fix typo in reset() description. docs/machine: Fix typo in reset() description.
ports: Switch to use lib/foo instead of duplicated code. ports: Switch to use lib/foo instead of duplicated code.
After the first line, add an empty line and in following lines describe After the first line add an empty line and in the following lines describe
a change in a detail, if needed. Any change beyond 5 lines would likely the change in a detail, if needed, with lines fitting within 75 characters
require such detailed description. (with an exception for long items like URLs which cannot be broken). Any
change beyond 5 lines would likely require such detailed description.
To get good practical examples of good commits and their messages, browse To get good practical examples of good commits and their messages, browse
the `git log` of the project. the `git log` of the project.
@ -47,14 +48,27 @@ address on it construes your sign-off of the following:
a valid and active email address by which you can be contacted in the a valid and active email address by which you can be contacted in the
foreseeable future. foreseeable future.
Code auto-formatting
====================
Both C and Python code are auto-formatted using the `tools/codeformat.py`
script. This uses [uncrustify](https://github.com/uncrustify/uncrustify) to
format C code and [black](https://github.com/psf/black) to format Python code.
After making changes, and before committing, run this tool to reformat your
changes to the correct style. Without arguments this tool will reformat all
source code (and may take some time to run). Otherwise pass as arguments to
the tool the files that changed and it will only reformat those.
Python code conventions Python code conventions
======================= =======================
Python code follows [PEP 8](http://legacy.python.org/dev/peps/pep-0008/). Python code follows [PEP 8](https://legacy.python.org/dev/peps/pep-0008/) and
is auto-formatted using [black](https://github.com/psf/black) with a line-length
of 99 characters.
Naming conventions: Naming conventions:
- Module names are short and all lowercase; eg pyb, stm. - Module names are short and all lowercase; eg pyb, stm.
- Class names are CamelCase, with abreviations all uppercase; eg I2C, not - Class names are CamelCase, with abbreviations all uppercase; eg I2C, not
I2c. I2c.
- Function and method names are all lowercase with words separated by - Function and method names are all lowercase with words separated by
a single underscore as necessary to improve readability; eg mem_read. a single underscore as necessary to improve readability; eg mem_read.
@ -64,7 +78,12 @@ Naming conventions:
C code conventions C code conventions
================== ==================
When writing new C code, please adhere to the following conventions. C code is auto-formatted using [uncrustify](https://github.com/uncrustify/uncrustify)
and the corresponding configuration file `tools/uncrustify.cfg`, with a few
minor fix-ups applied by `tools/codeformat.py`. When writing new C code please
adhere to the existing style and use `tools/codeformat.py` to check any changes.
The main conventions, and things not enforceable via the auto-formatter, are
described below.
White space: White space:
- Expand tabs to 4 spaces. - Expand tabs to 4 spaces.
@ -125,7 +144,7 @@ Braces, spaces, names and comments:
foo(x + TO_ADD, some_value - 1); foo(x + TO_ADD, some_value - 1);
} }
for (int my_counter = 0; my_counter < x; my_counter++) { for (int my_counter = 0; my_counter < x; ++my_counter) {
} }
} }