Proposed new feature or change:
New (and probably, continuing) developer experience could be improved a decent amount by including a docstring at the top of each python file. This can also help any users who utilize help to learn more about how to use the code.
Docstrings could be as simple as:
"""
File Purpose: UxDataArray class
"""
This helps to suggest there's nothing else important going on in the file; it's just all about defining the UxDataArray class.
Or, they can be more complicated, such as the one already in uxarray/core/accessors.py:
"""
Delegation-based accessor classes for UXarray groupby operations.
These classes wrap xarray's groupby/resample/etc objects and ensure that
operations return UxDataArray/UxDataset objects with preserved uxgrid.
"""
This allows you to quickly understand the purpose of the file, and also provides a nice place to include anything that isn't perfectly intuitive immediately from the file name. For example, uxarray/core/api.py currently has no docstring, so it takes a minute to realize this is the core public api, not an internal api, and not some other sort of api. A simple docstring like "File Purpose: core public api methods" would save that time and help avoid getting lost in the code.
Another good example is uxarray/core/zonal.py. When I was first exploring the code, before I read the readthedocs page, I initially thought maybe there could be a whole bunch of "zonal-related" methods. Now that I understand a bit more, I might put a docstring like:
"""
File Purpose: zonal averaging
Averages computed along one or more lines (or bands) of constant latitude.
"""
This defines what "zonal averaging" means, and clarifies that it is the entire purpose of the file; every method in this file is somehow connected to zonal averages, there's not any other type of "zonal" operation to watch out for.
Bonus benefits: these come up when applying introspection to modules directly, e.g. help(ux.core.accessors) includes the docstring above. Additionally, this matches xarray style, for example, you can import xarray as xr; help(xr.plot) or help(xr.tutorial), and you will see a description is included. Doing something like help(ux.grid) is currently sort of disappointing, there isn't any description about the basic purpose, nor any help suggesting where to look for more details.
Proposed new feature or change:
New (and probably, continuing) developer experience could be improved a decent amount by including a docstring at the top of each python file. This can also help any users who utilize
helpto learn more about how to use the code.Docstrings could be as simple as:
This helps to suggest there's nothing else important going on in the file; it's just all about defining the UxDataArray class.
Or, they can be more complicated, such as the one already in uxarray/core/accessors.py:
This allows you to quickly understand the purpose of the file, and also provides a nice place to include anything that isn't perfectly intuitive immediately from the file name. For example, uxarray/core/api.py currently has no docstring, so it takes a minute to realize this is the core public api, not an internal api, and not some other sort of api. A simple docstring like "File Purpose: core public api methods" would save that time and help avoid getting lost in the code.
Another good example is uxarray/core/zonal.py. When I was first exploring the code, before I read the readthedocs page, I initially thought maybe there could be a whole bunch of "zonal-related" methods. Now that I understand a bit more, I might put a docstring like:
This defines what "zonal averaging" means, and clarifies that it is the entire purpose of the file; every method in this file is somehow connected to zonal averages, there's not any other type of "zonal" operation to watch out for.
Bonus benefits: these come up when applying introspection to modules directly, e.g. help(ux.core.accessors) includes the docstring above. Additionally, this matches xarray style, for example, you can
import xarray as xr; help(xr.plot)orhelp(xr.tutorial), and you will see a description is included. Doing something likehelp(ux.grid)is currently sort of disappointing, there isn't any description about the basic purpose, nor any help suggesting where to look for more details.