Python Programming for Biology: Bioinformatics and Beyond

Code clarity

When it comes to writing clear Python code or generally being ‘elegant’ we wouldn’t want

to  give  fixed  rules  about  something  so  subjective.  However,  we  can  show  you  some

extremes  to  avoid  and  highlight  some  of  the  more  common  conventions  that  other

programmers  will  be  using.  Considering  the  following  versions  of  an  example  loop  in

Python, can you tell what it is supposed to be doing scientifically?

m = []

for a, b in l:

m.append(rf(a, b, 54.7))

How about this:

transResult = []

for globalCoordPosX, globalCoordPosY in mainCoordinateList():

transResult.append(angleTransformationFunc(globalCoordPosX,

globalCoordPosY, 54.7))

Or maybe:

newCoords = []

for x, y in coords:

newCoords.append( rotate(x, y, 54.7) )

It is often tempting to be lazy and use minimalist names for variables, but in the long

run, especially if you have to maintain the code, and understand what it means at a later

date,  this  approach  is  often  counterproductive.  Also,  if  you  write  clear  code  in  the  first

place there is much less need to document your programs. In contrast, great verbosity is

not always what is called for. Some verbosity is good, but too much obscures what you are

trying  to  do,  so  keep  it  simple  enough  to  be  obvious.  Single-letter  variables  can  be

absolutely fine in the right spot: usually where they are used immediately (e.g. in a loop)

or used for simple counters etc. The verbose example above also hints at something else

that can be very important, which is the choice of the variable names per se. The meaning

in English of a variable’s name should give a huge clue to what it does or represents, so

call a variable after what it is. And if it is a collection, like a list or set, consider using the

plural like coords  or  using  a  hint  like  coordList  or  coordSet,  so  you  never  have  to  think

what you have.

Some  readers  may  already  have  noticed  the  frequent  use  of  camel  case  in  this  book:

giving  names  humps  with  capital  letters  like  camelCase.  This  is  merely  convention  and

not  a  requirement  of  the  language.  While  you  will  see  it  frequently  in  Python  and  Java,

other languages more frequently have underscores, i.e. under_score, in order to join words

into variable names. There are several official Python style recommendations,

1

which the

authors admittedly don’t always stick to in the book, like indenting with four spaces (that

would mean running out of room or a really small font), but adhering to the spirit of these

---

and not being too silly with your placement of whitespace etc. really helps in the long run.

An  important  thing  about  coding  conventions  is  that,  as  long  as  there  is  consistency,

you can impart extra information. For example, for variable names the authors follow the

following  conventions.  If  a  variable  is  global  to  a  module,  i.e.  outside  all  functions  and

classes, as is common for constants, then it is written in upper case:

AVOGADRO_NUMBER = 6.02214e23

GYROMAG_RATIOS = {'1H':267.513, '2H':41.065, '13C':67.262, '15N':19.331,}

Function and regular variable names begin with lower case, but class names begin with

upper  case,  so  the  following  visually  represent  two  completely  different  things  in  our

convention:

snack = BananaSplit() # Object instance

twoHalves = bananaSplit() # function call

Naturally, functions are usually distinguished from regular variables by the presence of

parentheses.