Programming guidelines

Python version

Develop and test with Python 3.11 (aligned with CI in the Synarius repositories). Use a virtual environment created with that interpreter; avoid mixing binary wheels from different Python minor versions (e.g. cp311 packages under Python 3.12).

The synarius-core, synarius-apps, and synarius-studio packages declare requires-python = ">=3.11,<3.12" in each pyproject.toml. Installing with the wrong interpreter (for example Python 3.12) should fail at dependency resolution instead of leaving incompatible wheels.

Use python -m pip ... with the same interpreter that owns the virtual environment. When you change Python minor versions, recreate the venv and reinstall; do not copy or reuse site-packages from another Python.

Repositories and boundaries

Synarius is split into separate Git repositories; each can be cloned and used according to your needs.

synarius-core

  • GUI-less simulation and data backend.

  • Must not depend on PySide/Qt or Synarius Studio.

synarius-apps

  • Desktop tools and shared libraries: DataViewer, ParaWiz, synariustools (e.g. plot widgets).

  • Depends on synarius-core; does not require Synarius Studio. Useful for users who only need viewers or parameter workflows.

synarius-studio

  • Full graphical modeling and simulation IDE.

  • Depends on synarius-core and synarius-apps (via declared dependencies). Keep simulation logic in core, not in Studio.

Rule of thumb: simulation logic belongs in synarius-core; Studio and Apps focus on UI, tooling, and integration.

General Principle

  • Prefer clarity over cleverness.

  • Prefer flat structure over deeply nested structure.

  • Prefer well-named small methods over large monolithic ones.

Code style

  • Follow PEP 8 and project conventions in existing code.

  • Prefer small, focused functions and explicit behavior.

  • Add docstrings where they help maintainers (public APIs, non-obvious behavior).

Complexity and Nesting

  • Avoid deep nesting.

  • Prefer early returns (guard clauses) over nested if statements.

  • A method should generally not exceed 3 levels of indentation.

  • Methods with complex branching, nested loops, or nested try/except blocks should be split into smaller methods.

Loops

  • More than one loop in a method is a signal to review structure.

  • Multiple simple loops may still be acceptable if they belong to a single coherent task.

Extraction Criteria

Extract code into a separate method if one or more of the following applies: * The code can be given a clear, meaningful name. * It isolates error handling. * It separates parsing, validation, or transformation logic. * It improves readability by making the caller read like a sequence of domain-level steps.

Method Length

  • If a method is longer than 20 lines it should be condsidered to split it into smaller methods.

  • If a method has more than 1 loops it should be condsidered to split it into smaller methods.

  • Methods, which are only used by one other method and do only server limited technical purpose of the calling method and are not used in other places, should be inlined.

  • Inlined methods should be structured in this way: The first method should be a “run” method, which calls the other methods. The other methods should be private and only used by the “run” method.

  • Sumbethods of concructors must not be inlined, but should be named like “init_<name>” and follow the main contructor in the order of execution.

Method Structure (Orchestration Pattern)

  • Public methods should act as orchestrators, calling smaller private methods.

  • The structure should read like a sequence of clearly named steps.

  • Private methods should represent meaningful sub-operations of the algorithm.

Typing and tooling

  • Use type hints where they clarify interfaces; match the style of the repository you edit.

  • Formatting and linting: follow the checks configured in that repository’s CI when present.

Testing

  • New features should include tests where practical.

  • Bug fixes should include a regression test when feasible.

  • Run the relevant test suite (e.g. pytest) before opening a pull request.

Code Coverage

  • Code coverage is a measure of the proportion of code that is executed by tests.

  • The current goal is to achieve the following coverage for the codebase.

Part of Synarius

Coverage to achieve

synarius_core

75%

synarius_studio

40%

synarius_dataviewer

10%

synarius_parawiz

10%

synariustools

15%

  • These percentages will be adopted over time.

Pull requests

  • Keep changes focused and reviewable.

  • Describe what changed and why; reference issues when applicable.

  • Ensure CI passes for the target repository.

Repository-specific notes

  • synarius-core: run tests via pytest from the core package layout.

  • synarius-apps / synarius-studio: follow each repo’s CONTRIBUTING.md for additional hints (e.g. Studio icon conventions).

For legal and process details (e.g. CLA), see each repository’s CONTRIBUTING.md and CLA.md.