diff --git a/src/Mod/Arch/coding_conventions.md b/src/Mod/Arch/coding_conventions.md new file mode 100644 index 0000000000..9bd3fd8ee7 --- /dev/null +++ b/src/Mod/Arch/coding_conventions.md @@ -0,0 +1,4 @@ +# Arch coding conventions + +Since Arch is also a Python workbench, follow the same coding conventions +for the [Draft Workbench](../Draft). diff --git a/src/Mod/Draft/coding_conventions.md b/src/Mod/Draft/coding_conventions.md new file mode 100644 index 0000000000..ba662d93ef --- /dev/null +++ b/src/Mod/Draft/coding_conventions.md @@ -0,0 +1,130 @@ +# Draft coding conventions + +- These coding rules apply to the Draft Workbench. + Other modules or the base system may use different coding guidelines. +- These coding rules are essentially the same well known PEP 8 guidelines + that are recommended for all projects that use the Python programming + language; + for example, the [FEM Workbench](../Fem) + uses basically these same conventions. +- Draft is an old workbench, and thus the rules described here + are not followed strictly at the moment; + nevertheless, we are working on improving the situation over time. +- New code added to the workbench should adhere to these guidelines. + +## General + +- All files should have the license header at the beginning. +- Unix line endings should be used. +- Never use mixed line endings in the same file. +- Use 4 spaces for a single level of indentation. Do not use tabs. +- Remove trailing white spaces. +- Keep files at less than 1000 lines in size. + - Break a module into smaller modules, or into a package + (a subdirectory with various modules), + as necessary. + - A big function can be broken into smaller functions. + - A big class can be broken into smaller classes. + Then one class can subclass the other ones + in order to inherit their methods. + +## Python + +### Code formating + +- In general, code should follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) + and [PEP 257](https://www.python.org/dev/peps/pep-0257/) (docstrings). +- Maximum line length should be 80 characters. + - Find ways to reduce nested blocks of code by using auxiliary variables, + and functions that encapsulate the operations inside these blocks. + - If you have more than 3 levels of indentation, this is a sign + that the code should be refactored. +- Use double quotes for `"strings"`. + +### Imports + +- Imports should be at the beginning of the file, + after the license header and module docstring, + and they should be grouped in three types in order: + standard library imports, third party imports, + and then FreeCAD specific imports. +- Import only one module per line. +- Do not use asterisk imports, `from module import *`, as this + makes it hard to validate imported functions and classes. +- Do not import modules inside a function or class. +- The import of modules that require the graphical interface, + such as `FreeCADGui`, should be guarded by an `if FreeCAD.GuiUp:` test. +- In general, the code should be structured in such a way + that console-only functions are separate from their graphical interface + implementations (GuiCommands). + +### Naming policy + +- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/). +- `snake_case_names.py` for modules. +- `variable_names_without_capitals` for variables. +- `CamelCaseClass` for classes. +- `CONSTANTS_USE_CAPITALS` for constants. +- `functions_without_capitals()` for functions and class methods. +- Functions expected to return a value should indicate what is expected, + so `is_mesh_valid` is a good name, but `check_mesh` is not a good name. +- Class names, method names, and variables that are auxiliary, + and not meant to be part of the public interface should start + with an underscore like `_MyInternalClass` or `_my_small_variable`. + +### Python code formating tools + +- Using a code editor that automatically checks compliance with PEP 8 + is recommended. +- For example, [Spyder](https://www.spyder-ide.org/) + contains code checkers `pylint`, `pyflakes`, `pycodestyle`, `jedi`, + `sphinx`, etc., that automatically test the code as you write it, + and can provide documentation and hints on the used functions and classes + in real time, even the ones that you have just written. +- Compliance should be manually checked with [flake8](https://flake8.pycqa.org/en/latest/). +```bash +flake8 --ignore=E226,E266,W503 file.py +``` + +We may ignore certain errors and warnings. +- E226: spaces around arithmetic operators `*`, `/`, `+`, `-`; + sometimes we don't need a space. +- E266: only one `#` for comments; we need two `##` for Doxygen documentation. +- W503: break lines before a binary operator like `and` and `or`. + The W503 warning will be changed in the future so we can ignore it for now. +- See the meaning of the error codes in the + [pycodestyle documentation](http://pycodestyle.pycqa.org/en/latest/intro.html). + +A good way to test entire folders for compliance is to run +the following command. +```bash +find src/Mod/Draft -name '*.py' ! -name InitGui.py -exec flake8 --ignore=E226,E266,W503 --max-line-length=100 '{}' '+' +``` + +- The online [LGTM service](https://lgtm.com/projects/g/FreeCAD/FreeCAD/latest/files/src/Mod/Draft/) + is also able to analyze the code and detect problems. +- Avoid automatic code formaters. + +## C++ + +- Consider using [PEP 7](https://www.python.org/dev/peps/pep-0007/). +- In general, use the same naming style as with Python code. + +## Spelling + +- Take care of spelling mistakes in the default English messages, + graphical user interfaces, documentation strings, and source code comments. +- Use [codespell](https://github.com/codespell-project/codespell) + to find common errors. + +The following command tests files in the Draft directory, +but skips translation files and certain words which could be custom defined +variables, functions, and classes. +```bash +codespell -q 3 -S '*.ts' -L beginn,childs,eiter,methode,programm src/Mod/Draft +``` + +Interactively fix the errors found. +```bash +codespell -i 3 -w -S '*.ts' -L beginn,childs,eiter,methode,programm src/Mod/Draft +```