# `scripts/common/`

`scripts/common/` holds code used by more than one data source (NOAA, gridMET,
NSRDB, Köppen). Scripts import from it, for example
`from common.counties import load_counties`; nothing in it is run directly.

Rules for `common/`:

- **Cross-source only.** A helper goes in only if metrics from more than one
  data source use it. Code shared by scripts of a single data source stays with
  that source, for example a future NSRDB module for the NSRDB prompt,
  redaction, and error-log helpers.
- **One topic per module.** Each module is named for its topic and has a
  docstring. No catch-all `utils.py`.
- **Keep it small.** Before adding a helper, ask why it does not belong to any
  one data source.

Other shared code moves when its filter is reviewed, so each move is tested
alongside that filter. Duplicated and drifted helpers found by the 2026-09-13
survey are finding 14 in
[docs/reviews/00-cross-filter.md](../../docs/reviews/00-cross-filter.md).

Current modules:

| Module | Contents | Why it is in `common/` |
| --- | --- | --- |
| `county_zonal_stats.py` | Raster windows, the 180th-meridian split, area-weighted class shares | Used by any raster-based metric |
| `counties.py` | County polygon loading, FIPS normalization, the state FIPS table | County identity is shared by nearly every pipeline |
| `koppen_legend.py` | The Köppen code map and legend loader | Temporary: also used by `build_county_climate_data.py`; moves next to the Köppen code in Phase 3 |

**Rationale.** Helper functions make each step of a computation explicit,
avoid repeated code, and can be tested separately
([Brown CSCI 0111, "Helper Functions"](https://cs.brown.edu/courses/csci0111/fall2018/lectures/helper-functions.html)).
Shared helper folders, however, tend to lose cohesion and collect unrelated
code; the recommended alternative is to keep code with the part of the system
it belongs to, allowing a shared folder only if it stays small and documented
([Helpers and Utils Folders in Software Architecture](https://dev.to/knzt/helpers-and-utils-folders-in-software-architecture-3f8h)).
The rules above follow both: shared functions, organized by topic and limited
to code that crosses data sources.