Please open notebook rsepython-s4r2.ipynb
Let’s import the context for this chapter.
from context import *
Consider the following fragment of python:
import species
def AddToReaction(name, reaction):
reaction.append(species.Species(name))
this could also have been written:
from species import Species
def add_to_reaction(a_name,
a_reaction):
l_species = Species(a_name)
a_reaction.append( l_species )
Consider these two code fragments, they are the same, just presented differently.
Which is easier to read?
Fragment 1:
reaction= {
"reactants": ["H","H","O"],
"products": ["H2O"]
}
Fragmet 2:
reaction2=(
{
"reactants":
[
"H",
"H",
"O"
],
"products":
[
"H2O"
]
}
)
We have a number of choices when laying out our code.
The final presentation is a combination of:
Inconsistency will produce a mess in your code! Some choices will make your code harder to read, whereas others may affect the code. For example, if you copy/paste code with tabs in a place that’s using spaces, they may appear OK in your screen but it will fail when running it.
Camel case is used in the following example, where class name is in UpperCamel, functions in lowerCamel and underscore_separation for variables names.
This convention is used broadly in the python community.
Example 1:
class ClassName(object):
def methodName(variable_name):
instance_variable=variable_name
This other example uses underscore_separation for all the names.
Example 2:
class class_name(object):
def method_name(a_variable):
m_instance_variable=a_variable
In Hungarian notation, a variable name starts with a group of lower-case letters which are mnemonics for the type or purpose of that variable, followed by whatever name the programmer has chosen.
Prefix denotes type, in this instance ‘float’:
fNumber= float(sInput) + iOffset
So in the example above we know that we are creating a float number as a composition of a string entry and an integer offset.
People may find this useful in languages like Python where the type is intrinsic in the variable.
number = float(input) + offset
Use newlines to describe your code’s rhythm
In these examples you can see that it is possible to write code fragments that produce the same outcome in different ways.
Example 1:
anothervariable+=1
if ((variable==anothervariable) and flag1 or flag2): do_something()
Example 2:
anothervariable = anothervariable + 1
variable_equality = (variable == anothervariable);
if ((variable_equality and flag1) or flag2):
do_something()
We create extra variables as an intermediate step. Don’t worry about the performance now, the compiler will do the right thing.
What about operator precedence? Being explicit helps to remind yourself what you are doing.
You should try to have an agreed policy for your team for these matters.
If your language sponsor has a standard policy, use that.
There are automated tools which enforce coding conventions and check for common mistakes.
These are called linters
E.g. pip install pycodestyle
%%bash
pycodestyle species.py
species.py:2:6: E111 indentation is not a multiple of four
It is a good idea to run a linter before every commit, or include it in your CI tests.
There are other tools that help with linting that are worth mentioning. With pylint you can also get other useful information about the quality of your code:
pip install pylint
%%bash
pylint species.py
***** Module species
species.py:2:0: W0311: Bad indentation. Found 5 spaces, expected 4 (bad-indentation)
species.py:1:0: C0111: Missing module docstring (missing-docstring)
species.py:1:0: C0111: Missing class docstring (missing-docstring)
species.py:1:0: R0205: Class ‘Species’ inherits from object, can be safely removed from bases in python3 (useless-object-inheritance)
species.py:1:0: R0903: Too few public methods (0/2) (too-few-public-methods)
————————————-
Your code has been rated at -15.00/10
and with black you can fix all the errors at once.
black species.py
These linters can be configured to choose which points to flag and which to ignore.
Do not blindly believe all these automated tools! Style guides are guides not rules.
Finally, there are tools like editorconfig to help sharing the conventions used within a project, where each contributor uses different IDEs and tools. There are also bots like pep8speaks that comments on contributors’ pull requests suggesting what to change to follow the conventions for the project.
Next: Reading - Comments