Patrick Fitzsimmons Blog

How to name variables and methods when coding in a dynamic language

pfitzsimmons@hubspot.com (Patrick Fitzsimmons) — Thu, 12 Dec 2013 16:00:00 GMT

Dynamic languages lack the perfect IDE intellisense that tells us the type of every variable. Thus it is necessary to use variable names that allow future readers of the code to unambiguously determine the type and contents of the variable.

Method names

Method names should always be verbs or verb phrase - get_person, load_database, mark_job_completed, etc.

If the method has side effects and alters a passed in object (generally a bad idea but sometimes OK), then be explicit by using the verb 'fill' or 'hydrate':

def hydrate_context(context):
    context['stuff'] = Stuff()

def fill_context(context):
    context['stuff] = Stuff()

If the method has side effects that alter a permanent datastore, use a verb like 'update_db', 'save', or 'persist'

If you are grabbing a remote resource, use the verb 'fetch' rather than 'get' to imply that the code is reaching out a distance to get the content:

def fetch_embed_html():
    return requests.get(self.url)

If your method does two things (generally a code smell, but sometimes you just need a method that wraps two other methods), then be explicit about what the method does and what it returns:

def fetch_and_normalize_embed_html(self):
    html = self.fetch_embed_html()
    return self.normalize(html)

If you have a variable that holds some sort of callback function, add 'callback' or 'method' or 'function' to the variable name:

#GOOD:
def process_task(task, success_callback, error_callback):
    ''' Do stuff ... '''

# BAD (It's unclear that "error" is a callback function, "error" could be anything, a message that's passed in, a list that collects error results, etc):
def process_task(task, success, error): 
    pass

If you want to add a simple getter to an object, use a verb in the method name if it's a method, or use a property if there is no verb in the name. Do not create verbless methods. (This is a python specific rule. Javascript does not have getters, and so using methods that are just the attribute name is quite common in jQuery).

GOOD:
def get_host(self):
    return self.request.host

GOOD:
@property
def host(self):
    return self.request.host

# BAD ( I will be very confused when I do "print obj.host" and get "<function host>" instead of the host name)
def host(self):
    return self.request.host

Object instances

Object instances should be the lower case version of the class name, ex: game_type = GameType(), file_library = FileLibrary()

Sometimes this seems to verbose. You are tempted to write 'library' instead of 'file_library'. But remember, code is read many more times than it is written. Optimize for the developer reading the code four months from now, not for your typing speed this second.

Lists

Variables holding lists should always be the plural form of the thing the list is holding:

    for person in people:
    for name in names:
    for account in accounts:

Dictionaries

Dictionaries are basically used in two different ways - as schemaless objects or as a lookup table.

object-style dictionary usage

If you are in a small, standalone script, that uses almost all dictionaries and no classes, then it is OK to name the variable holding the dictionary for what the thing is:

person = {
    'name': 'jim',
    'birthdate': '4-17-1982',
    'hometown: 'Boston'
    }

But if you are in code that has a class Person, and you have a dictionary that is storing some serialized form of that class, then naming that dictionary 'person' creates confusion. Use 'person' to refer to an object instance, and use 'person_data' or 'person_dict' to refer to the dictionary form, and use 'person_str' or 'person_json' to refer to the serialized form:

person = Person()
person_data = Person.to_dict()
person_json = json.dumps(person_data)

Dictionaries as lookup tables

If the dictionary refers to some sort of mapping or lookup table, then name the variable for the lookup key and value:

# GOOD:
person_by_name = {
    'jim': Person(),
    'sam': Person()
}

cities_by_country = {
    'United States': ['Boston', 'New York'],
    'France': ['Paris', 'Orleans']
}

action_to_func_map = {
    'deploy': deploy_project,
    'kick' : kick_project,
}

# BAD - the code reader will think this ia list of persons, not a dictionary
persons =  {
    'jim': Person(),
    'sam': Person()
}

In general, name the variable either 'value_by_key' or 'key_to_value'.

Never name a dictionary just 'persons' or 'cities'. The code reader will have no idea how to use the variable. They will think it is a list and be very confused to find it is a lookup table. Once they figure out it is a table, they will be unsure what the keys are.

Strings

Strings should end in a postfix that indicates stringness/wordness. Examples of good string variable names include: author_name, field_label, img_src, template_source, body_text, page_key, data_str. If you have a variable holding a users name, do not call that variable 'user', because someone reading the code will get it confused with an instance of the User class. Call the variable user_name. Do not call a string holding the name of a file 'file', that confuses it with a file object. Call the string 'file_name' if it's just the file name, or 'file_path' if it contains the full path to the file.

Numbers

Numbers should end with a postfix marking the variable as clearly numeric. Do not use plurals only as that makes the variable name confusing with lists – use 'result_count' not 'results'. Other examples: item_id, home_price_int, costs_sum, load_avg

Err on the side of being unambiguous at the expense of verbosity. Let's say you have a variable in a page template. The variable contains the percent of people who passed some academic test. If you name this variable 'percent_passed', it is not immediately obvious if the variable contains a string that looks like '34%' or a float that contains .34. Instead, name your variable 'percent_passed_formatted' for the string version and 'percent_passed_float' for the float version to make it obvious.

General Consistency

Try to be consistent within your code, so that a variable name always indicates the same thing wherever it is used.

For instance, create a convention whereby:
(thing)_file is an instance of a file object
(thing)_file_name is a string with the name part of the file 'mystuff.txt'
(thing)_path is a string with the file full path: '/home/patrick/mystuff.txt'

Do not have (thing)_file be a file object in one place and a file name in another place.

If in your app 'thing_guid' refers to a string, then it should always be a string. If it refers to an instance of a uuid() or Guid() object, then it should always refer to the instance, and never have a type of string. Pick one way and be consistent.

Using Judgement

The above guidelines should be followed 99% of the time for naming class attributes, module attributes, and method parameters. For local variables or loop variables, you can use your judgment. Since the variable is initialized so close to where the variable is used, it can be pretty obvious to the person reading the code exactly what it is in it, and thus having a verbose variable name is less critical.

If you want to work at a company where you will get fussy code review comments if you name your variables poorly, my company, HubSpot, is hiring software engineers. We&squot;re one of the fastest growing startups in the greater Boston area. Check out our jobs page to learn more about our culture and the type of work available." class="hs-cta-img" style="border-width:0px" src="https://no-cache.hubspot.com/cta/default/498/9997a77e-681b-40e7-b383-7dab8737c9a1.png">

While-loops Considered Harmful

pfitzsimmons@hubspot.com (Patrick Fitzsimmons) — Wed, 20 Feb 2013 16:30:00 GMT

Your phone buzzes with the server alert ring tone. Your product manager taps you on the shoulder: "Um, it looks like we're down." Not a single screen in your web app loads. You attempt to SSH into your server but connecting takes for...ev...er. Finally you connect to the shell and see the CPU pegged at 100%. You tail the access logs, but nothing looks fishy. Site traffic is normal. Frantic and desperate, you reboot the server. The server comes back up ... but immediately the CPU spikes back to 100%.

An hour later you find the problem. That hour seemed like an eternity as you tore your hair, fended off account managers, grepped every line of source you could find, and wondered what it feels like to get fired. And what was the error? It was a while loop that processed some unexpected input and spun forever.

Infinite loop bugs are among the most insidious and - outside of wiping out customer data - most destructive bugs. In web application development, most bugs only affect the particular code path where the buggy code resides. Most of the time you know what paths are most critical and can give those paths an extra thorough review. But a while-loop bug in some unimportant, admin-only screen can disable the entire application for everyone. When the problem strikes, it is very difficult to figure out what exactly is causing the app to freak out and where the buggy code lives.

Fortunately, there is a solution to avoid this class of bug completely: never write a while-loop.

Anywhere in your code where the need arises for a while loop, instead write a "for-loop" with a sensible maximum.

For example, let us say that I am doing a standard chunked-file read in python. In my younger days I would write:

f = open('file.mp3', 'r')
while True:
    chunk = f.read(4000)
    if not chunk:
        break
    output.write(chunk)

A better pattern is:

# pick a number comfortably higher than the logic of the function
# needs to support.
EMERGENCY_BRAKE = 10000000 
for x in xrange(0, EMERGENCY_BRAKE):
    chunk = f.read(4000)
    if not chunk:
        break
    output.write(chunk) 
if (x+1) >= EMERGENCY_BRAKE:
    raise Exception("File reading loop hit the emergency brake")

Even better, you can write a helper method:

def iter_with_brake(max_times=1000000):
    for x in xrange(0, max_times + 1):
        if x == max_times:
            raise Exception("Iteration exceeded maximum")
        yield x

And now you can use this helper any time you would have previously used a while-loop:

for x in iter_with_brake():
    chunk = f.read(4000)
    if not chunk:
        break
    output.write(chunk)

In the trivial case of reading a file, the lack of an emergency brake is unlikely to cause a problem. But when you start creating more complicated while-loops, such as for tree traversal, streaming parsers, etc., while-loops become very dangerous. I therefore highly recommend eliminating them entirely.

(Note for the pedantic: this blog post targets web application programmers. There are of course cases in software development where while loops are still fine. If you are writing the main event loop for a sensor on the next Pioneer space probe, your while-loop should happily keep plugging away until the end of the universe).

Check out our jobs page to learn more about our culture and the type of work available." class="hs-cta-img" style="border-width:0px" src="https://no-cache.hubspot.com/cta/default/498/7a67aaa5-0890-464f-b290-21d408a73628.png">

How to Turn Your Windows Machine into Unix

pfitzsimmons@hubspot.com (Patrick Fitzsimmons) — Fri, 13 May 2011 15:58:00 GMT

For the many years, the requirements of my job forced me to use Windows for working on parts of our code base. When working in Windows, I dearly missed the tools of a unix environment (ls, grep, the shell, etc). But over the years I've figured out a bunch of hacks that make using Windows a lot more tolerable. Here they are:

1) Install a real text editor - Vim or Emacs. The optimized key bindings and extra power of Emacs/Vim allow you write code or prose with amazing speed. Read Steve Yegge if you're not convinced. Put emacs in the system path, so that as you browse around in the shell you can edit files by entering ">emacs file.txt"

2) Install the GNU utils for windows and put them on your system path. Now you can use all your favorite unix utilities such as grep, touch, ls, diff, etc, from your windows command line.

3) Enable copy/paste from the command line. In the windows command prompt, click on the icon in the upper left and then click properties. Then set "Quick Edit" mode to checked. Now you can copy text by highlighting it with the mouse and hitting enter. You can paste by clicking the middle mouse button.

4) Install a better shell. I prefer IPython. IPython gives you most of the bash functionality and key bindings. Type Ctrl-r to search for previous commands. Ctrl-A to move to the beginning of the line, ctrl-k to kill a line, ctrl-y to paste/yank a line back, etc. The tab completion works like unix where it only completes until the point of ambiguity. The only annoying thing is that you must prefix all shell commands with "!". But on the plus side, you also have an interactive python prompt, which is handy if you need to test a snippet of code or do some quick math.

5) Remap Caplocks to trigger ctrl. Cap-locks is basically useless. Ctrl is used all the time in programming, especially if you use emacs. Remapping will make you type far more efficiently.

6) Forget about Cygwin. Cygwin offers the promise of a full unix shell from within windows. But the Cygwin environment has too many pieces that are broken or incompatible. You feel like you are in unix, but then you try to run a script and you get a deep down stack trace. You spend six hours trying to debug it before finding that the underlying C-library is simply incompatible with the Cygwin environment. If you want to use linux on your windows box without dual booting, use a full VM like Colinux or VM Ware. I keep a small, headless, Colinux, Centos5 process running in the background that I SSH into if I need to do something that is linux only.

About me

pfitzsimmons@hubspot.com (Patrick Fitzsimmons) — Tue, 28 Oct 2008 04:52:00 GMT

I am a startup guy and software engineer. I currently am working on co-founding Grokky. Before that, I worked at HubSpot for the better part of a decade. At HubSpot I helped build a powerful suite of marketing software tools that served 10,000 plus paying customers.

Stuff I've Built

HubSpot Content Optimization System (2011-2014)

I was the tech lead for the team building the next generation of the HubSpot content tools. We have built tools for creating blog posts, landing pages, emails, and full web sites. Features include visual template building, a powerful templating language, WYSIWYG editing, A/B testing, and integration with the contacts system and analytics.

My personal responsibilities included: designing and/or reviewing overall architectual decisions, mentoring and doing code reviews for a team of 12 people, writing tens of thousands lines of code, working with the product manager to find the proper technical solution to business problems, attending usability sessions and proposing UI design changes, performing devops tasks to ensure we could have less than an hour of total downtime on our public facing pages over the course of a year.

The system was built in python running on django. The backend was implemented mostly as REST-ful API's, while the frontend used backbone and custom javascript.

HubSpot Analytics and Sources Application

I co-lead a team that built an analytics system that would allow our customers to discover where visitors so their site originated from and how they converted into customers and leads, in a set of easy to use charts and tables.

The project used python and java for the programming, and the log processing jobs ran on Hadoop.

Various Projects at HubSpot

In addition to the major projects listed here, during my seven years at HubSpot I have engaged in numerous smaller projects:

a sales tool to crawl web sites and discover what marketing products the prospect was using
an embedable javascript widget allowing visitors to follow the page creator
a desktop executable for Windows and Mac OX that watches a directory for changes and updates files, blog posts, templates, CSS files and other resources to the COS API
a prospects report that would display information about all web site visitors based on GeoIP lookups

HubSpot Content Management System - Version 1 ( 2006-2008)

When I joined HubSpot I took over the early prototype of the HubSpot content tools, which was a custom DotNetNuke installation running in VB on the ASP.NET stack. I converted it to C# and rebuilt the UI to make it something easy for marketers to use with a drop drop controls. I also built out features such as analytics dashboards, a drag and drop form builder, an inline content editor, and a browser based template editor.

GroupSharp 2005

My senior year at a college I founded a company to build a way for non-technical users to build and host an online database. I took the project from initial idea to the point where I was making money advertising via Google Adwords and selling subscriptions to the product. The company was "acquihired" by HubSpot.

Lanovision and Coffeeshop

During college I developed an application to share music and videos with other people in the dormitory.

Areas of Experience

Web applications in Python/Django
Building my own frameworks and tools in Python, including Sprocket for building aspect oriented API's, and Mockery for easy mocking in unittests.
Single page web apps using JavaScript, CoffeeScript, HTML5, and Backbone.
Web applications and services in Java, using Hibernate, Jersey, and (and in the older days, Struts)