CODECONVENTIONS.md: Update to reflect use of new tools/codeformat.py.
Updated (back) for Pycopy.
@@ -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) {
}
}
