-
Notifications
You must be signed in to change notification settings - Fork 117
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Util (& Helper) Functions #46
Comments
Thanks for this overview! I agree that the As a side note:
|
All good points! Just wanted to add an example of a function that I think should be rather a utility than a class function: In |
I agree on all that's been said - a cleanup within the util functions is definitely worthwhile. I think the only realistic way of reducing existing duplicate logic throughout the code base is if someone can dedicate time specifically to refactoring. If we're able to visualise the dependency structure of functions and methods within CLIMADA (sort of like pyreverse UML, see classes_climada.pdf), I think that new contributors could better avoid introducing redundancies. Regarding Maybe off topic: it may be necessary to overthink the setup procedure anyways if we're going to package CLIMADA: |
This was rediscussed in the CLIMADA code convention of 11.12.2020. A very minimal consensus was to promote better the existence of the util functions in the developer's guide, the coding conventions, and the code reviews. |
Should this discussion continue or can it be closed? |
For the time being we stick to the current implementation. |
Issue Description
I'd like to deviate a bit from this location-only focus of the issue and add the following:
Some background
What is a util function? What is a helper function? Are there meaningful differences?
Most sources admit the terms util and helper are used ambiguously and inconsistently. There is no very clear consensus about their distinction.
Some point out that "helper" functions could simply be sub-functions of a main function, used for refactoring & readability purposes within one single module, whereas the term util makes the inter-modular use purpose relatively explicit.
I'll use the term util functions from now on for the scope of this issue, referring to short, re-usable, relatively general functions performing repetitive tasks.
How are we handling util functions at the moment in climada?
In folder climada/util we have 10 files that contain some sort of util functions (and 4 other items: config.py, constants.py, test/, and earth_engine, which is a module that never quite made it to a stand-alone feature and was hence dumped into util)
Checking "references" of use of those util functions via github's code navigation tool reveals that, while indeed many are used in several modules, quite a few of those util functions are used only by one module or not at all (i.e. apart from its definition and a corresponding unit test)
Example
alpha_shape
coordinates
checker
scalebar_plot
The logic of how util functions are currently grouped within those 10 files is not always very intuitive (e.g. there is a file_handler, but also a hdf5_handler, which is a file-format, after all)
Checking some of the code base, there are many instances of module-agnostic, repetitive tasks that could be handled by a util function (mostly reading / loading files, converting dates / times, handling strings, converting object-types, etc.)
Example
Will add examples!Propositions
Location in folder "utils" generally makes sense. However: Should there be some naming hint in the scripts to distinguish scripts containing util funcs form other scripts in that folder (
config
,earth_engine
,constants
), e.g.ufuncs_scriptname.py
?Make a list of currently "unused / single-used" functions in utils, try to find author & critically reflect its potential future use in utils vs relocation to specific module.
"Awareness raising" on new util functions: Should people send around some kind of notification to currently active climada developers when they add a new util function that is potentially useful to others, incl. short description of what it can do? E.g. via slack / mail? If on the other hand, no use-case can be imagined --> reflect on whether this function really needs to go to utils
Re-structuring of some of the scripts to logically group util functions (I did not find a good overview on "common util classes", I guess that's a bit project specific. Ideas for further "groups" will be welcome.
Example
ufuncs_plot.py?
--> functions for plotting, maybe move scalebar_plot to this as well?ufuncs_file_handlers.py
--> functions for opening / reading, closing / saving any kind of files. Maybe also the current hdf5_handler script?ufuncs_interpolation.py
--> seems quite sensible to meufuncs_dates_times.py
--> also quite sensible grouping. See lots of potential for those functions to be used more! And other datetime conversions to be added to this!...
The text was updated successfully, but these errors were encountered: