Need solid naming conventions

[lo-co]

Obviously as described in #3 we need some standardization. Discuss this here.

[lo-co]

So, here are a couple of examples that I pulled from the current repo of naming gone awry:

pl = tools.stopping_distance(temperature=temperature,
                                 pressure=pressure,
                                 particle_diameter=particle_diameter,
                                 particle_velocity=particle_velocity,
                                 particle_density=particle_density,
                                 verbose=verbose)

and

def loss_at_an_abrupt_contraction_in_circular_tubing(temperature=293.15,  # Kelvin
                                                     pressure=101.3,  # kPa
                                                     particle_diameter=1,  # µm
                                                     particle_density=1000,  # kg/m^3
                                                     tube_air_velocity=False,  # m/s
                                                     flow_rate_in_inlet=3,  # cc/s
                                                     tube_diameter=0.0025,  # m
                                                     contraction_diameter=0.00125,  # m
                                                     contraction_angle=90,  # degrees
                                                     verbose=False,
                                                     ):

My suggestion is that we pretend for a moment that not all of us work in an environment with autocomplete. Imagine trying to type this. Surely we can do better (I am going to propose a suggestion for sampling efficiency calculations down the line, so don't get too bent about this yet).

Also, I believe that we can surely come to some kind of agreement regarding proper truncation of names. I propose these for some common ones:

• d: diameter
• rho:density
• eta: efficiency
• u: velocity
• q: flow rate
• ang: angle
• p: pressure
• t: temperature or time

Append characters to provide a more understandable definition. Here are a couple that I use:

• 0: initial
• p: particle

Also, for the sake of readability, do not comment the method signatures - this is what docstrings are for.

Any thoughts?

[hagne]

I like it as it is and don't see the need to change it. Also, I can't really imagine anyone not using auto completion. Since there are so many arguments it is really usefull to have the full name, this spares you from having to read the documentation.

[lo-co]

Hagen - it is virtually unreadable in pycharms. The second example is an absolute deal breaker for me - I often work with multiple screens and when your one function signature extends beyond the margin things become a real pain in the ass. If the module is called sampling_efficiency and you have a method called eta_contraction, I am pretty certain I know what it is doing. And, if it has inputs like

eta_contraction(t, p, dp, rho_p, u,...)

I don't think there is anything unreadable about this. Comment away in the code. Make your functions readable in the context of the module. But FFS, don't use sentences for function or variable names. Believe it or not, I and others don't always want to have to pull up an IDE to write code and nobody should be forced to. I would challenge you to find an example of this in an existing, widely used repo where you have function names that are ~50 characters long.

And, we use abbreviations all the time in the way we speak with each other and write in the literature (not sure there are many instances where I use single particle mobility sizer or continuous flow diffusion chamber rather than SMPS or CFDC). If you are writing code, we can probably assume that you are not a complete dumbass. Remember that we do this in the context of our work as scientists, so if you see t, p... when calculating something involving temperature and pressure, you likely will know what that means.

[lo-co]

Check out this discussion on SO. While this is just all opinion, the contributors seem to be in some agreement (the original example was check_5_theVersionOfAllVPropsMatchesTheVersionOfTheAutolinkHeader()):

The OP says:

well thanks, but for the readability part, I can't let that count: This is exactly what I'm trying to achieve here. The name of the function tells you what it does. If I abbreviate it, it becomes less readable.

to which someone responds:

Your code will be absolutely unreadable. Use docstrings.

and another

"Fully descriptive" and "readable" are two separate things. Long, long camel-cased strings are the former, not the latter.

and finally an awesome example (although in camel case, but it still holds)

Because functionsThatTellYouExactlyWhatTheyDoInCamelCase(areReallyAnnoyingBecauseItAllRu‌​nsTogether).

[hagne]

If it is so important to you feel free to change it.

[lo-co]

Nah...