Developer's guide: Maintainable code development

Introduction

We strive to keep the codebase of Pty-Chi clean, organized, readable, maintainable and extendable. This needs all contributors to adhere to good software engineering practices.

Comply with software architecture

Pty-Chi adopts an object-oriented design that involves multi-level class hierarchy and orthogonalized data structures (see a UML diagram here). The principles below should be followed when integrating changes into the codebase:

• Honor class hierarchy. If a class method or attribute is applicable to all subclasses, put it in the base class. For example, a routine usable by all analytical ptychography reconstructors should be inserted in AnalyticalIterativePtychographyReconstructor which is the base class of all such reconstructors.

• Choose the right class. If a routine is heavily dependent on the inherent attributes of a class, make it a method of that class. For example, probe mode orthogonalization is a method of Probe instead of being implemented in a Reconstructor class.

• Subclass when necessary. For routines that are used only in specific scenarios, create a subclass of the proper class and implement the routines there instead of putting everything in the existing class. For example, deep image prior-represented object is implemented in DIPObject which is a subclass of Object.

• Not everything needs to be class methods. If a routine does not need to reference any attribute of a class, and is supposed to be called in different classes and modules, consider implementing it as a utility function in a proper module such as maths.py or image_proc.py.

Code style

We follow PEP-8 for code style. This includes, but is not limited to the following:

• Use all-lower-case letters for variable names. Separate words with underscores. Do not capitalize variable names even for those that are commonly capitalized in mathematical notations, such as matrices. Use postfixes to indicate their nature. For example, instead of A for a matrix, use a_mat.

• Capitalize each word without using underscores for class names. For example, AnalyticalIterativePtychographyReconstructor.

• Use proper white spaces around operators, but don't over do it. Do not add extra spaces to make lines of codes aligned.

More details can be found on PEP-8 documentation. Additionally, we commonly use double quotes (") instead of single quotes (') for string literals.

Commenting out large blocks of code just to bypass them is strongly discouraged and will not pass code review when it is present in a submitted pull request. If you really need to include a block of code that should be skipped now but might be resumed in future commits, put them in a function or class method and raise NotImplementedError at the beginning. However, this is not encouraged either.

We highly recommend using Ruff to lint and format your code before submitting a pull request.

Documentation and annotations

Functions, methods and options should be properly documented and annotated to improve their readability and usability. Functions and methods should have a docstring enclosed in triple quotes under the signature. We use NumPy/SciPy format for docstrings. If the inputs or outputs involve tensors or arrays, state their expected shapes unless the shapes are arbitrary. Inputs and outputs should also be type-annotated. If the function signature is long, put each input argument in its own line. See below for an example of a properly documented and annotated function:

def get_probe_mode(
    p: torch.Tensor, 
    mode: int
) -> torch.Tensor:
    """Get the specified incoherent mode of a probe.

    Parameters
    ----------
    p: torch.Tensor
        A (n_opr_modes, n_incoherent_modes, h, w) tensor giving the probe.
    mode: int
        The mode to get.
    """
    return p[:, mode, ...]

Fields in Options classes should also be annotated and documented. For example:

threshold: float
"""The threshold of segmentation."""

Binary files

Binary files, except necessary images used in documentations, should never be pushed to the source code. Input data and gold data for CI testers are stored in a separate repository in APS GitLab. If you want to include additional data for CI, please contact the developers.