Skip to content

software_practices.md

Latest commit

 

History

History
58 lines (38 loc) · 3.21 KB

software_practices.md

File metadata and controls

58 lines (38 loc) · 3.21 KB

Software practices

Core principles

Scientists and engineers are expected to adhere to a set of core principles about our software.

Style

These standards are maintained by the aind-library-template. Use the template when creating new packages. Our maintained templates are:

Template URL
Python package https://github.com/AllenNeuralDynamics/aind-library-template
Code Ocean capsule ...
Code Ocean pipeline ...
Analysis capsule ...

The decision to deviate from these style standards must be made in consultation with an entire team and be manager-approved. Deviations must be implemented by modifying the pyproject.toml.

Standard

Package management should be handled by uv.

We use ruff to enforce PEP 8 standards with docstrings in NUMPY format. Use ruff check and ruff check --fix. Line lengths should have a maximum of 100 characters.

Releases should follow semantic versioning with major.minor.patch versions. Only external-facing packages should be published to pypi, internal packages should be installed from github releases. Use the following prefixes to trigger version updates automatically after merges to main:

| Prefix | Commit message | Update | | <any>: | | patch | | feat: | | minor | | feat!: or fix!: | Include BREAKING CHANGE and details | major |

Unit tests should use pytest. Coverage should be at 100%. Tests should be run before merging pull requests into main and dev.

GitHub automation should use the AIND reusable workflows.

Recommended

  • Functions to be annotated with type hints.
  • Functions should not exceed a complexity of 10 paths (ruff default).
  • Functions should return early / fail fast.
  • Code should be capable of being analyzed by static analysis tools.
  • Modules (<1000 lines), classes, and functions (<100 lines) should be manageable size.
  • Internal packages should use the naming pattern <modality>-<process> wherever possible.
  • Packages should not be prefixed with our namespace (i.e. do not put aind- as a prefix).
  • Internal dependencies should be pinned ==1.0.0 or use both a version floor and ceiling >=1.0.0,<2.
  • Unit tests should cleanup test files or write to temporary folders. Do not version auto-generated code or data in repositories.

Code Review

[TODO UPDATE] At least one other software developer needs to approve a pull request in order for it to be merged. Please be courteous when providing feedback. The team lead can resolve any conflicts.

Resources for SWEs

For research software engineers, Good Research Code is a good primer.

Data structure fundamentals