From 54a54f5872ae489547f84600aab8471e6e83d715 Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 28 Feb 2020 12:35:19 +1100 Subject: [PATCH] CODECONVENTIONS.md: Update to reflect use of new tools/codeformat.py. --- CODECONVENTIONS.md | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/CODECONVENTIONS.md b/CODECONVENTIONS.md index 982b958313..b18c9818ad 100644 --- a/CODECONVENTIONS.md +++ b/CODECONVENTIONS.md @@ -11,7 +11,7 @@ It's also ok to drop file extensions. Besides prefix, first line of a commit message should describe a 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: py/objstr: Add splitlines() method. @@ -19,9 +19,10 @@ of good first line of commit messages: docs/machine: Fix typo in reset() description. ports: Switch to use lib/foo instead of duplicated code. -After the first line, add an empty line and in following lines describe -a change in a detail, if needed. Any change beyond 5 lines would likely -require such detailed description. +After the first line add an empty line and in the following lines describe +the change in a detail, if needed, with lines fitting within 75 characters +(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 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 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 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: - 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. - Function and method names are all lowercase with words separated by a single underscore as necessary to improve readability; eg mem_read. @@ -64,7 +78,12 @@ Naming 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: - Expand tabs to 4 spaces. @@ -125,7 +144,7 @@ Braces, spaces, names and comments: 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) { } }