Notes on a consistent package

List of things to keep consistent that we cannot keep track of with linters or tests:

1. Syntax of docstrings and arguments

We are not counting bytes from lines of code anymore nowadays, variable naming and description should be as intuitive and clear as possible while maintaining conciseness 😉.

• Argument or variable naming: Use short name if clear like "crop_geom" or "ref", otherwise full name, such as "raster", "bounds", or "points",
• Docstring of method/attribute: Start with a one-sentence summary of the function/attribute. Then start a new paragraph below the one-sentence summary describing specifics, only if necessary and without duplicating information already in the parameter descriptions. For instance: "Crop the raster to a given extent. // // Match-reference: a reference...",
• Parameter description: Start with a very short one-sentence description, for example "crop_geom: Geometry to crop raster to.", follow-up with important details. Ignore types already declared by typing. However, specifying default is good if important to the function, even if it also appears in the function definition.
• References: Always add the reference to a related scientific paper if used, or to the function of another package if central to the calculation (and for looking up kwargs).

2. Link to user interface

Trying to make it as easy for users to learn the package!

• Raising errors: Try to propose solution in errors instead of simply raising the issue. For example: "Both CRS and shape must be the same for the rasters. You can do this by using raster1 = raster1.reproject(raster2)...",
• Homogenize function argument/names: When adding a new function, try to look for other function that had the same argument, and copy names/descriptions to stay 100% consistent,
• Consistent behaviour: For instance, have all operations modifying a certain object in a similar way to have the same inplace or other parameters by default. We detail the choices we made for GeoUtils further below.

3. Behavioral choices for GeoUtils

• Single-band raster is always 2D (array squeezed, band dimension removed),
• Lazy loading is always default (loading=False),
• In-place behaviour is never default (inplace=False), and is implemented as argument for all methods returning the same object modified,
• Implicit passing of CRS is always default (and directed towards match-reference object),
• Raster array is always a NumPy masked array (forced by from_array() or during instantiation),
• Raster and Vector can be defined without CRS (or transform), but will raise errors during certain operations. TO-DO: Not sure this is fully covered by tests/behaviour right now.