Coding Conventions

Relevant source files

The following files were used as context for generating this wiki page:

• src/Mod/Draft/coding_conventions.md
• src/Mod/Fem/coding_conventions.md
• CONTRIBUTING.md
• src/Mod/CAM/Roadmap/ADR/ADR-000.md
• src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md

Coding conventions in Parashell provide a unified framework for development across various workbenches like Draft, FEM, and CAM. These guidelines ensure code quality, maintainability, and consistency, particularly for Python and C++ contributions. As Parashell is a fork of FreeCAD, it adheres to the FreeCAD Contribution Process (FCP) and leverages established standards such as PEP 8 for Python.

The project emphasizes modularity, clear naming policies, and specific formatting rules to reduce technical debt and simplify collaborative development. While older modules may still contain legacy code that diverges from these rules, all new contributions are required to adhere to the current standards.
Sources: src/Mod/Draft/coding_conventions.md:3-10, CONTRIBUTING.md:1-5

Python Standards and Formatting

Python code in Parashell generally follows PEP 8 and PEP 257 (docstrings) guidelines. There are specific constraints on file size and complexity to maintain readability.

Code Structure and Length

Files should be kept under 1000 lines. Large components should be refactored by breaking modules into packages, functions into smaller utility functions, and large classes into inherited hierarchies.
Sources: src/Mod/Draft/coding_conventions.md:20-27

Metric	Requirement
Maximum Line Length	80 characters (Draft) / 100 characters (FEM)
Indentation	4 spaces (No tabs)
Indentation Depth	Maximum 3 levels before refactoring
String Identifiers	Double quotes ("string")
Line Endings	Unix (LF) only
Sources: src/Mod/Draft/coding_conventions.md:16-19, 31-36, src/Mod/Fem/coding_conventions.md:23-28

Import Guidelines

Imports must be grouped at the beginning of the file following a specific hierarchy to minimize merge conflicts and improve clarity.

This diagram illustrates the mandatory ordering of imports in Python modules.
Sources: src/Mod/Fem/coding_conventions.md:46-60, src/Mod/Draft/coding_conventions.md:42-45

Rules for Imports:

• One import per line.
• Do not use asterisk imports (from module import *).
• GUI-specific modules (e.g., FreeCADGui) must be guarded: if FreeCAD.GuiUp:.
• Grouping: Standard library > Third-party > Non-GUI Core > Workbench-specific > GUI modules.
  Sources: src/Mod/Draft/coding_conventions.md:46-52, src/Mod/Fem/coding_conventions.md:40-44, 61-63

Naming Policies

Naming conventions vary slightly by module but generally follow the snake_case for functions/variables and CamelCase for classes.

Entity	Style	Example
Modules	snake_case	path_utils.py
Variables	snake_case	mesh_buffer
Functions / Methods	snake_case	get_mesh_data()
Classes	CamelCase	MeshProcessor
Constants	ALL_CAPS	MAX_ITERATIONS
Internal/Private	Leading underscore	_internal_helper
Sources: src/Mod/Draft/coding_conventions.md:60-68, src/Mod/Fem/coding_conventions.md:83-86

Functions returning values should be descriptive of the result. For instance, is_mesh_valid is preferred over check_mesh.
Sources: src/Mod/Draft/coding_conventions.md:69-70

C++ and Integration

C++ development is encouraged to follow PEP 7. Naming styles should generally match the Python conventions (CamelCase for classes/methods) to maintain a cohesive API across the hybrid environment.

• Line Endings: Strictly Unix LF; .gitattributes are used to enforce this.
• Formatting: Avoid excessive use of slashes in comments as they can interfere with Doxygen parsing.
• Tools: Use clang-format for automated formatting before submission.
  Sources: src/Mod/Fem/coding_conventions.md:24-25, 115-117, src/Mod/Draft/coding_conventions.md:92-93

Exception Handling and Logging

Parashell requires specific practices for error management and console output to ensure that the system remains robust and debugging is straightforward.

• Exceptions: Do not use bare except:. Be specific or use except Exception: (or BaseException if absolute capture is required).
• Printing: Use FreeCAD.Console.PrintMessage(), Log(), or Error() instead of Python's standard print(). The print() function is reserved for temporary local debugging only.
• Type Checking: Avoid hasattr(obj, "Proxy"). Instead, use workbench-specific utilities like is_of_typ(obj, "TypeString").
  Sources: src/Mod/Fem/coding_conventions.md:33-38, 97-104

Contribution Process (FCP)

Contributions are managed through a Pull Request (PR) workflow on GitHub.

The sequence of events from identifying a problem to merging a solution in the Parashell repository.
Sources: CONTRIBUTING.md:125-145

PR Requirements:

• Must resolve exactly one identified problem.
• Each commit must compile cleanly.
• Titles must be succinct; bodies must document UI changes with screenshots.
• Attribution must be provided if code is cherry-picked from elsewhere.
  Sources: CONTRIBUTING.md:75-103

Tooling and Validation

Compliance is enforced through a mix of automated tools and manual review.

• flake8: Used for Python PEP 8 compliance checks.
• codespell: Used to identify and fix spelling mistakes in English messages, docstrings, and comments.
• LGTM: Online service for detecting deep-seated code problems.
• black: Recommended for formatting new Python code in certain workbenches (e.g., FEM).
  Sources: src/Mod/Draft/coding_conventions.md:83-88, 97-100, src/Mod/Fem/coding_conventions.md:88-95

Conclusion

The coding conventions in Parashell serve as the technical foundation for a professional, industry-ready CAM and modeling solution. By enforcing strict Python formatting, standardizing naming across languages, and following a rigorous contribution process, the project minimizes technical debt and encourages a diverse pool of contributors to maintain code quality. All developers are expected to utilize the recommended validation tools like flake8 and codespell to ensure their submissions align with these project-wide standards.