Description
We currently specify a default particle in keyword arguments for most of our functions in the physics subpackage (including in a bunch of code that I originally wrote). An sample:
from plasmapy.atomic import particle_input, Particle
@particle_input # turn a particle string into a Particle class instance
def particle_mass(particle: Particle = 'e-'):
return particle.mass
The disadvantage of setting a default particle is that users could end up making incorrect assumptions or interpretations of the results. We do state the assumptions in the documentation, but I know I personally often just skim through documentation without reading it in detail and could end up missing something like this. Different fields also assume different default ions (e.g., deuterons in fusion vs. protons in astronomy). In some cases, users may not immediately realize that a particle needs to be specified. These implicit assumptions can also make the resulting code less readable for someone who is unfamiliar with the package:
>>> particle_mass() # unclear which particle we are finding the mass of
<Quantity 9.10938356e-31 kg>
Since explicit is better than implicit, I propose that we do not specify default particles in keyword arguments for our functions so that an exception is raised when particle information is not provided, and instead either not set a default particle (for positional arguments) or set the default particle to None
(for keyword arguments):
@particle_input
def mass_of_particle(particle: Particle):
return particle.mass
@particle_input
def particle_massiveness(particle: Particle = None):
return particle.mass