Project Style Guide

🎨 This guide explains the coding and formatting conventions used in the project, and how to keep things consistent when adding or editing code.

It combines Python code conventions, documentation standards, and metadata formatting guidelines.

🧑‍💻 Python Coding Conventions

✅ Function Definitions

Use type hints for all parameters and return types.

def convert_units(
    values: xr.DataArray,
    current: str,
    target: str,
) -> xr.DataArray:
    ...

🐍 Naming

Functions and variables: snake_case
Constants (e.g., in xarray datasets): ALL_CAPS

📝 Docstrings

Use NumPy-style docstrings
Required for all functions.
Sections include: Parameters, Returns, Notes, (optionally Examples, References)

Example:

def convert_units_var(
    var_values: xr.DataArray,
    current_unit: str,
    new_unit: str,
    unit_conversion: dict = unit_conversion,
) -> xr.DataArray:
    """
    Convert variable values from one unit to another.

    Parameters
    ----------
    var_values : xr.DataArray
        The numerical values to convert.
    current_unit : str
        Unit of the original values.
    new_unit : str
        Desired unit for the output values.
    unit_conversion : dict, optional
        Dictionary containing conversion factors between units.

    Returns
    -------
    xr.DataArray
        Converted values in the desired unit.

    Notes
    -----
    If no valid conversion is found, the original values are returned unchanged.
    """

📚 NumPy-style docstrings render cleanly in Sphinx documentation (e.g. on Read the Docs). See NumPy docstring style.

💡 Alternatives like Google-style and reST-style docstrings are also valid with Sphinx if configured properly.

🗂 Dataset & Metadata Conventions

🧬 Variable Names

Variable naming conventions are currently inconsistent across the codebase
We need to verify and align with OceanSites variable naming recommendations
Mix of ALL_CAPS (TIME, DEPTH) and lowercase (temperature, pressure) currently in use
Keep names short and unambiguous

🧾 Attributes

Follow OceanSites format conventions
Use units, long_name, comment
Avoid placing units in variable names — use attributes instead

📐 Consistency

Units are checked and converted using helper functions
Time is standardized using utility functions across the project

🔁 Automating Formatting

The project uses tools like black, ruff, and pytest to enforce style, linting, and test consistency. These are integrated into the workflow using pre-commit hooks.

Pre-commit tools used:

black .                         # Format code with black
ruff check .                    # Run ruff linter  
ruff check . --fix              # Auto-fix issues where possible
pre-commit run --all-files      # Run all pre-commit hooks
codespell                       # Check for spelling errors

You don’t need to run them manually, but setting up pre-commit ensures your code follows project standards automatically.

🛠 Optional: VSCode Setup for Auto-formatting

To automatically format code when you save a file, add this to your Workspace Settings (.vscode/settings.json):

{
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  }
}

You can also add a VSCode task to format manually:

{
  "label": "Format Code",
  "type": "shell",
  "command": "black . && ruff check . --fix",
  ...
}

Then bind it to a keyboard shortcut (e.g. Cmd+Shift+R) or run it from the command palette.

💡 Future Considerations

Add mypy for static type checking
Use Sphinx for auto-generating documentation (already partially configured)

✅ By following these conventions, your code will integrate smoothly with the rest of the project — clean, consistent, and ready for collaboration.