Coding_Standards

Intro

The primary goal of the NISAR Quality Assurance code is to perform Quality Assurance for the NISAR L1/L2 science products produced by ISCE3.

However, the QA code also serves as a testbed for cleaner, modern code design patterns and styles. These practices have been discussed and agreed upon by the NISAR QA code developers, and are actively used in the QA codebase.

• Before submitting any PR, go through this checklist.
• New contributors must review this list.
• Reviewers should not be afraid to reference it.

This is a living document. It should evolve with the codebase. Contributions and suggestions encouraged.

Non-Negotiable Coding Standards

• numpy docstrings
  • Include Parameters and Returns for 99% of functions.
  • See: https://numpydoc.readthedocs.io/en/latest/format.html
• pathlib / os.PathLike
  • Where possible, use these instead of str filepaths
• Black formatting
  • Black can be added as an extension in VSCode
  • Specify the version of Black via the pyproject.toml file and a .pre-commit-config.yaml
• isort for sorting import statements
• Forbid wildcard imports
  • The exception: ok in __init__.py
• Add type annotations
  • Some older QA code lacks this
  • MyPy linter and analyzer to enforce type annotations
• Use __main.py__ for command line interface
• "Reviewer-Friendly" -> See Checklist below

Preferred Standards

These are style and design patterns each contributor should make a best effort to adopt. They are meant to prevent maintainability headaches and technical debt in the future.

If a preferred standard is broken, please document VERY THOROUGHLY what the new code is doing and why. If it's too painful to document that thoroughly, consider refactoring.

• Prefer Pure Functional code when reasonable.
  • Avoid modifying arguments in place; document clearly if needed, or consider an optional "out" parameter
  • Prefer no side effects. If there are side effects, note them in the docstring.
• Prefer typing.Protocol over ABC (Abstract Base Class)
• Prefer Python dataclasses (where it makes sense)
• Prefer pyproject.toml over setup.py
• Flat namespaces for majority of modules
  • To achieve this in QA code, do this for every new module:
    • Set __all__ in the new module. (See: src/nisarqa/__init__.py > get_all(...))
    • In the __init__.py in same directory as the new module, import the new module using a wildcard.
      • Then ensure that subdirectory is imported in its parent's __init__.py, recursively until reaching src/nisarqa/__init__.py.
    • Make sure your function names are unique within the QA code
  • This will bring the module's functions into the nisarqa namespace.

Reviewer-Friendly Checklist

aka How to keep reviewers happier, to get your PR reviewed/approved faster, and save hours of time and frustration for everyone in the long run

• Good Docstrings
• Clean interfaces
• Smaller PRs
• Put stylistic changes and functional changes into separate PRs.
• Comments that:
  • Explain as if the reader knows nothing
  • Explain the motivation of what's going on:
    • What is the step is doing?
    • Why is it doing it?
    • Why is it doing it this way?
      • Ex: Are there gotchas that you figured out and had to code around? Cool! Write them down. The reviewer will also wonder why you did not use something simpler.
    • Include any assumptions, including units of input values, etc.
    • Advanced Request: Comments are "information dense"

Good Coding Practices

Multiple style guides document good coding practices. Here are a few practices that have arisen during code reviews and discussions:

• Code Reuse
• Single Responsibility Principle
• If you smell code stink... stop. Refactor.
• If a line of your code prompts a 5 minute discussion, capture that discussion in a new comment.