Skip to content

Make error messages clearer and more informative #1617

Description

@Sevans711

Proposed new feature or change:

Error messages throughout uxarray could be made clearer and more informative.

For example:

    if not uxda._node_centered():
        raise ValueError(
            f"Data Variable must be mapped to the corner nodes of each face, with dimension "
            f"{uxda.uxgrid.n_face}."
        )

could be improved to something like:

    if not uxda._node_centered():
        raise ValueError(
            f"Expected node-centered data, got {uxda.data_location}, for node-to-edge aggregation. "
            f"(Face-centered data has n_face dimension of size {uxda.uxgrid.n_face})."
        )

The latter has the following benefits:

  • uses more common terminology ("node-centered" instead of the current version's "mapped to the corner nodes of each face")
  • gives relevant information about the actual state of objects which caused the failure (uxda.data_location indicates "face_centered" or "edge_centered", as opposed to the current version which does not say where the data is actually centered)
  • briefly clarifies what was being attempted when the error occurred ("node-to-edge aggregation")
  • clarifies what the uxda.uxgrid.n_face number means.
    • (The original message was quite confusing to me. For example, I don't really know what to think about the "4730" when just seeing "Data Variable must be mapped to the corner nodes of each face, with dimension 4730." And, if I had to guess, I would guess "ah, 4730 must be the expected size of the data variable, i.e. the number of nodes" but that is actually incorrect, it is the expected size of the result after mapping from nodes to faces.)

This is merely one example. There are many error messages throughout uxarray which could be improved. Fully addressing this issue would involve looking through all uxarray error messages (there are over 250 of them), which may be infeasible to do or review all at once. Perhaps one reasonable way to address this issue could be over the span of multiple PRs, each focused on a single section of the code, with PRs like "Make uxarray/grid/ error messages clearer and more informative" focused on the uxarray.grid subpackage, and similar PRs for "core", "plot", etc.

This is complementary to #1556, which proposes to swap to using custom error types, but should avoid editing error messages directly.

Metadata

Metadata

Assignees

Labels

developer experienceMakes the codebase easier to read, debug, maintain, or extend.documentationImprovements or additions to documentationimprovementImprovements on existing features or infrastructureredesignContent relating to the ongoing redesign

Type

No type

Projects

Status
📝 To-Do

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions