How to write reusable (but not usable) code

Source

How to write reusable (but not usable) code

Python is an easy and powerful language for machine learning practitioner like me. A good style makes the code easy to read and reuse. A lengthy one comes from Google. Here, I want to share with you some tips to create troubles when others want to use your code.

Actually, I want you to avoid them.

To keep things tight, a short list followed by detailed examples in below.

  • Write out-dated (and misleading) comment
  • Mix controllable parameter and hard-coded parameters
  • Save parameters in configuration file and never share it
  • Access variables, functions, classes via string in the name of dynamic
  • Give the same name to similar (but different) functions
  • Mis-spell function name

Write out-dated (and misleading) comment

Code keeps evolving, just checkout how many versions of Tensorflow or PyTorch per year. People are rushing to develop new features and sometime need to change their code. Please make sure the supporting documents are up-to-date.

In [ ]:
def get_number():
  """ return a number"""
  return "I changed my mind"

Mix controllable parameter and hard-coded parameters

It is always nice to have a versatile function rather than many hand-coded parameters. However, consistency is critical to make everything right.

In [ ]:
def create_two_same_size_lists(n=10):
  return list(range(n)), list(range(10))

Save parameters in configuration file and never share it

Using parameters from a configuration file is definitely preferred, which will save you a lot of time to track your ML experiments. However, do please remember to share it with your collaborators, at least one working version.

In [3]:
import json
config = json.load(open("config.json"))

---------------------------------------------------------------------------
FileNotFoundError                         Traceback (most recent call last)
<ipython-input-3-c342cb5df34c> in <module>
      1 import json
----> 2 config = json.load(open("config.json"))

FileNotFoundError: [Errno 2] No such file or directory: 'config.json'

Access variables, functions, classes via string in the name of dynamic

Using string to access classes or functions can be very powerful and dynamic. However, it will leave the code hard to maintain, e.g. hard to trace definitions, prone to error. If really needed, check whether you can use a dict to track all definitions.

In [4]:
class A:
  def __init__(self):
    self.a=1

getattr(A(), 'a')
Out[4]:
1

Give the same name to similar (but different) functions

Once a project grows larger and larger, it might be easier to write a handy function instead of searching and reusing existing functions. But it is very harmful if the same function name servers in different parts of the code for different purposes.

In [5]:
def get_sum(a):
  return sum(i for i in a)

def get_a_sum(a):
  return sum(i**2 for i in a)

Mis-spell function name

A common problem, esp. working on the server side. Please use some spell checker.

In [6]:
def data_louder():
  return 1,2,3,4

Comments