Here are some rules that help you to write code of high quality. They are inspired by Michael Toppa - 10 Tips For Clean Code
- Choose meaningful variable names
- Boy Scout Principle: Leave the code base cleaner than you found it
- Single Responsibility Principle: A function / method does only one thing
- Write Tests
- Independent Architecture
- Many arguments -> pass object,
- Signal to noise ratio: How much of the desired signal is there compared to parts you don't want?
The principles layed out below can be grouped in several categories:
- Mental Load: Understanding code is difficult. Some principles help to reduce the difficulty.
- Speed: Make the code run faster
- Extendability: Code is rarely ever finished. New features have to be added all the time. Principles with this tag make it easier to extend the code in a clean way.
if 'key' in a_dictionary: foobar = a_dictionary['key'] else: foobar = 'a default value'
foobar = a_dictionary.get('key', 'a default value')
- Easier to read, because less lines of code Mental Load
- Looking up 'key' only once Speed
Error case checking
A common problem is to check many error-cases until you do whatever you want to do.
def foo(bar): if a(bar): b = c(bar) if b != 'xy': doit(bar)
def foo(bar): if not a(bar): return b = c(bar) if b == 'xy': return doit(bar)
The reason why code structured like this is because:
- Mental Load Easier to read - first error checking, then the stuff that needs to be done
- Extendability: Imagine there was another error case you forgot that needs to be checked in the beginning. Then, using the pattern above, you would need to reindent all of the code.
Make Variable Names Pronouncable
- Mental Load When you write a comment, could it rather be a better variable name?
- When you write a comment, should it be a log statement?
NamedTuples instead of Tuples
>>> from collections import namedtuple >>> Point = namedtuple('Point', ['x', 'y']) >>> Point <class '__main__.Point'> >>> Point(133, 123) Point(x=133, y=123)
- Extendability In places that might be far from the point of creation of the tuple, it is way easier to understand what this was about.
- Debugging In places that might be far from the point of creation of the tuple, it is way easier to understand what this was about
Keyword-Arguments instead of positional arguments
Minimum variable length
grep a lot when I develop. For projects I work on I have a very rough
call graph in mind, so I know a bit how my projects modules / objects interact
with each other. When I want to extend functionality, I grep for the part where
I need to adjust things (or I simply use Ctrl + f).
Hence, for every semantically meaningful variable it is good to have variables
which are not parts of other words. A common one where it is fine to have a
short name is having iterators that are just
i (an index integer). A common
one which I don't like is
t0 = time.time() some_code() t1 = time.time() execution_time = (t1 - t0) / 3600
t0 = time.time() some_code() t1 = time.time() SECONDS_IN_A_HOUR = 3600 execution_time_in_hours = (t1 - t0) / SECONDS_IN_A_HOUR
Reasons why it is better:
- Extendability It is easier to understand which formats are converted here.
Even better: Use a unit library like pint. This way, it is guaranteed that the units will not accidentially be used in the wrong way.
import pint ureg = pint.UnitRegistry() execution_time = (t1 - t0) * ureg.second execution_time.to(ureg.hour).magnitude
First List Pop
del list_ list_.pop(0) list_.insert(0, 'foobar')
Reason: Speed - see time complexity of data structure operations
Avoid Mental Mapping
list_ = ['[email protected]', '[email protected]', '[email protected]'] for i in range(len(list_)): send(list_[i])
email_addresses = ['[email protected]', '[email protected]', '[email protected]'] for email_address in email_addresses: send(email_address)
Mental Complexity Here we don't iterate over an integer number. We iterate over items. Those items have a semantic type. What would we say in natural language to describe the code? Surely something like:
To each email address which we gathered before, we send a mail.
The last one is was closer to this natural form than the other two ones are.
try: os.remove('foobar') except OSError: pass
@contextmanager def ignored(*exceptions): try: yield except exceptions: pass
with ignored(OSError): os.remove('foobar')
Don't add unnecessary prefixes / suffixes
For example, a
Person class does not need a
person_id property. It is
simply an id.
Use at most 3 function parameters
This is not a hard rule, but certainly one that most often is a good idea. Functions with many parameters are super hard to digest. Often, it makes more sense to pass the function an object, e.g. a namedtuple.