pymedphys / pymedphys

A community effort to develop an open standard library for Medical Physics in Python. Building quality transparent software together via peer review and open source distribution. Open code is better science.
https://docs.pymedphys.com
Apache License 2.0
309 stars 73 forks source link

Collection of contribution recommendations #1230

Open SimonBiggs opened 3 years ago

SimonBiggs commented 3 years ago

Module importing as per https://docs.python-guide.org/writing/structure/#modules

eg, import the module not the functions within the module so that they are namespaced within the code.

SimonBiggs commented 3 years ago

Avoid defining classes, aim to build pure functions as opposed to objects that carry state with methods that contain side-effects.

This and other issues led to the idea that using stateless functions is a better programming paradigm.

Another way to say the same thing is to suggest using functions and procedures with as few implicit contexts and side-effects as possible. A function’s implicit context is made up of any of the global variables or items in the persistence layer that are accessed from within the function. Side-effects are the changes that a function makes to its implicit context. If a function saves or deletes data in a global variable or in the persistence layer, it is said to have a side-effect.

Carefully isolating functions with context and side-effects from functions with logic (called pure functions) allows the following benefits:

  • Pure functions are deterministic: given a fixed input, the output will always be the same.
  • Pure functions are much easier to change or replace if they need to be refactored or optimized.
  • Pure functions are easier to test with unit tests: There is less need for complex context setup and data cleaning afterwards.
  • Pure functions are easier to manipulate, decorate, and pass around.

In summary, pure functions are more efficient building blocks than classes and objects for some architectures because they have no context or side-effects.

From https://docs.python-guide.org/writing/structure/#object-oriented-programming

SimonBiggs commented 3 years ago

The ImageJ philosophy page is quite brilliant:

https://imagej.net/Philosophy

SimonBiggs commented 3 years ago

...try to make a pit of success... :) https://ricomariani.medium.com/pit-of-success-for-organizations-a046a0eae7b2

SimonBiggs commented 3 years ago

Some further discussion around object orientation within Python:

https://leontrolski.github.io/mostly-pointless.html