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 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 formatting

• In general, code should follow PEP 8 and PEP 257 (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.
• 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 formatting tools

• Using a code editor that automatically checks compliance with PEP 8 is recommended.
• For example, Spyder 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.

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.

A good way to test entire folders for compliance is to run the following command.

find src/Mod/Draft -name '*.py' ! -name InitGui.py -exec flake8 --ignore=E226,E266,W503 --max-line-length=100 '{}' '+'

• The online LGTM service is also able to analyze the code and detect problems.
• Avoid automatic code formatters.

C++

• Consider using PEP 7.
• 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 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.

codespell -q 3 -S '*.ts' -L beginn,childs,eiter,methode,programm src/Mod/Draft

Interactively fix the errors found.

codespell -i 3 -w -S '*.ts' -L beginn,childs,eiter,methode,programm src/Mod/Draft