search

mne-tools / mne-python

MNE: Magnetoencephalography (MEG) and Electroencephalography (EEG) in Python
https://mne.tools
BSD 3-Clause "New" or "Revised" License
2.66k stars 1.31k forks source link

Clarify and document our submodule layout principles #12711

Open drammock opened 1 month ago

drammock commented 1 month ago

I think it would be useful to clarify/discuss why the other stats functions do not get to live in their own namespace. What's the rationale behind it? Is it the number of (expected) functions?

Originally posted by @cbrnr in https://github.com/mne-tools/mne-python/issues/12707#issuecomment-2223245312

drammock commented 1 month ago

I think these questions should have easy-to-find answers for our (new) contributors and maintainers:

  1. How do I decide where in the API to expose my new functionality?
    • sub-question: when to make a function, method of an instance, or both?
  2. When should a .py file start with an underscore?
  3. When should I put all submodule functions in one file vs. in a directory of several files?
  4. What should go in the __init__ file of a submodule?
hoechenberger commented 1 month ago

While I appreciate the effort (thanks @drammock!) I'm not convinced that strict rules are of much help here. I'd propose to decide ad-hoc on a case-by-case basis.

drammock commented 1 month ago

I agree that for point (1) it will probably need to be case-by-case. To the extent that we can, being more descriptive/verbose in our submodule docstrings might encode this information.

I think we also have some related (possibly unwritten) norms that it would be helpful to capture, e.g., for the subpoint under 1, "functions return copies of instances (or some other kind of object), whereas methods modify the instance in place."

Points 2, 4, and maybe 3, I feel like we could probably at least agree on guidelines; e.g. for point 4 I've seen some software that defines classes / functions in submod/__init__.py rather than in submod.py (a practice which startled me, though IDK if it's actually frowned upon). In cases where there's a known best practice, we can say "we follow best practice Y (link to Y)" and in other cases we can say "in MNE, we do it like V and not like W (even though either way would work)"