Documentation¶
Add docstrings
No:
def typical_function_in_the_lab():
...
v =+ 1
...
1 sentence for obvious functions:
def add_1(v):
"""Add 1"""
return v+1
Full docstring for non trivial cases. Start with a summary line, give a full explanation (even with use cases) and explain the arguments an the return:
def create_table(s1, s2):
"""
Create a enrichment table.
Args:
s1 (set): genes to evaluate
s2 (set): reference genes
Return:
table. Amount of genes in s1 that are in s2 for each group of 5 genes.
"""
...;
For full docstrings there are several formats. Although reST format is the “officially recommended”, I prefer Google docstrings as they are more readable, in my opinion.
You can find examples in https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format
In the Ipython console use ? to access the docstring:
create_table?
and ?? to access the whole code:
create_table??
Comments¶
When possible, put them on a line of their own
Use them sparingly and avoid unnecessary comments
No:
x = x + 1 # Increment x
Yes:
x = x + 1 # Compensate for border
Prefer code readability to writing a lot of comments
No:
# If the sign is a stop sign
if sign.color == 'red' and sign.sides == 8:
stop()
Yes:
def is_stop_sign(sign):
return sign.color == 'red' and sign.sides == 8
if is_stop_sign(sign):
stop()
Codetags¶
Codetags are special markup conventions that serve as reminders of sections of code that need closer look or revision.
Specially useful can be TODO or FIXME tags:
# TODO: allow list to be passed
# FIXME: loop should be finite
Hint
In Pycharm they have a tool to to list of the TODO and FIXME entries. It can be found under