tl;dr;

Unless the function you are writing is a getter (which complements a setter), please avoid naming methods get_.

get_ lacks descriptiveness, precision, and is boring.

Rationale

Software engineers are supposed to creative, and get is possible the least creative function name possible.

Too often, I see codebases cluttered with get_ methods throughout, when the implementations of those methods do things far more complex than simply reading or getting a value from an object.

When half of a file with hundreds of lines of code are all named get_*, this makes code difficult to read, scan, and reason about. (Future blog posts will address code that is easy vs difficult to reason about.)

Alternatives

Since much of the world’s software (historically) has been produced from within English-speaking countries and by English-speaking programmers and software engineering teams, please allow me introduce to you the robustness of the English language.

While my hope and expectation is not for every software engineer to have a Shakespearean command over English vocabulary, I do think that it is quite tenable to learn a few prefixes to help codebases become more manageable and pleasing to read.

Without further ado, these are my suggestions:

• build_
• calculate_
• extract_
• fetch_
• look_up_ / retrieve_
• format_ / transform_

Below are examples and sample code, in Python (my language of choice).

build_

When to use it: Use this prefix for a method which takes in some data, and builds a more complex structure as a result.

Analogy: You have multiple loose LEGO bricks, and want to assemble those pieces to build a structure out of that.

Bad

def get_response(color, food, location):
    response = {
        'color': color,
        'food': food,
        'location': location,
    }
    return response

Good

def build_response(color, food, location):
    response = {
        'color': color,
        'food': food,
        'location': Location(location),
    }
    return response

Usage

response = build_response('green', 'eggs and ham', 'in a car')

# Result:
# {
#     'color': 'green',
#     'food': 'eggs and ham',
#     'location': {
#         'name': 'in a car'
#     },
# }

calculate_

When to use it: When you have some data, and some formula is applied to calculate a result.

Analogy: If it’s not doable via “mental math,” and needs to be calculated.

Setup

items = [
    {
        'color': 'green',
        'food': 'eggs and ham',
        'location': {
            'name': 'in a car'
        },
        'price_cents': 1525,
    },
    {
        'color': 'red',
        'food': 'hot chili peppers',
        'location': {
            'name': 'with a mouse'
        },
        'price_cents': 299,
    },
    {
        'color': 'orange',
        'food': 'carrots',
        'location': {
            'name': 'here or there'
        },
        'price_cents': 399,
    },
]

Bad:

def get_total(items, unit='cents'):
    total_cents = sum([item['price_cents'] for item in items])

    if unit == 'cents':
        total = total_cents
    elif unit == 'dollars':
        total = float((Decimal(total_cents) / Decimal(100)).quantize(Decimal('1.00')))
    
    return total

Good:

def calculate_total(items, unit='cents'):
    total_cents = sum([item['price_cents'] for item in items])

    if unit == 'cents':
        total = total_cents
    elif unit == 'dollars':
        total = float((Decimal(total_cents) / Decimal(100)).quantize(Decimal('1.00')))
    
    return total

A method named calculate_ will mentally prepare the engineer to be extra careful and meticulous when maintaining this code, because the goal is to be accurate and precise.

extract_

When to use it: When you need one, or a few pieces of information, from a more complex structure.

Analogy: You have a plain rock (diamond ore, gold ore) which is relatively useless on the surface, and want to extract the valuable contents (diamonds, gold).

Setup

response = {
    'color': 'green',
    'food': 'eggs and ham',
    'location': {
        'name': 'in a car'
    }
}

Bad

def get_color(response):
    return response['color']


def get_location_name(response):
    return response['location']['name']

# Usage

color = get_color(response)
location_name = get_location_name(response)

Better

response = {
    'color': 'green',
    'food': 'eggs and ham',
    'location': {
        'name': 'in a car'
    }
}

def extract_color(response):
    return response['color']


def extract_location_name(response):
    return response['location']['name']

# Usage

color = extract_color(response)
location_name = extract_location_name(response)

Great

Consider using object-oriented programming:

class Response:
    def __init__(self, raw_response):
        self.raw_response = raw_response

    @property
    def color(self):
        return self.raw_response['color']

    @property
    def location_name(self):
        return self.raw_response['location']['name']

# Usage

r = Response(response)

color = r.color
location_name = r.location_name

fetch_

When to use it: Use this prefix when the method makes an HTTP call or other API call. Inspired by fetch from JavaScript (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)

Analogy: If you have a warm and cuddly friendly dog, and you’re at the park playing the good ol’ game of fetch; the object you’re intending to retrieve is accessible to you, but not immediately within reach.

Bad

def get_story_details(story_id):
    response = requests.get(f'https://api.example.com/story/{story_id}/details')
    return response

If the method is named get_, there’s no way to distinguish at a glance whether this function calls out to another server/service.

Whenever the flow of your code leaves your control (like making an API call), there is inherent risk and potential for errors to occur (e.g. “What if the remote API goes down?”)

Good

def fetch_story_details(story_id):
    response = requests.get(f'https://api.example.com/story/{story_id}/details')
    return response

By naming methods that make API calls to remote resources withfetch_, you allow engineers to quickly identify risky sections of code at a glance, without requiring them to read the details of a function – and this saves time – allowing a flywheel effect of: by writing code faster, teams produce more code / fix bugs more quickly, delivering more business value, enabling these teams to hire more team members, to build more products….

So, if I see a method named fetch_, I can immediately make mental note to make these sections of code more resilient (such as with try and except error handling, retry logic with exponential backoffs, etc).

look_up_

When to use it: Use this prefix when the goal of the method is to retrieve data that was previous stored in a local storage, like a database.

Analogy: There is a single piece of information you want to retrieve from among a larger collection, like *looking up** the defintion of a word in a glossary.

Setup

# MySQL

| id | item              | price_cents |
----------------------------------------
|  1 | eggs and ham      |        1525 |
|  2 | hot chili peppers |         299 |
|  3 | eggs and ham      |         399 |

Bad

def get_price(item):
    sql = connect()
    q = sql.query('items').where(item=item)
    price = q.execute()['price_cents']
    return price

Better

def look_up_price(item):
    sql = connect()
    q = sql.query('items').where(item=item)
    price = q.execute()['price_cents']
    return price

By naming a method look_up, you mentally prepare the next engineer who reviews this code that this method involves some form of database retrieval, and they can also keep in mind the performance characteristics of database retrieval.

Best

Use the database repository design pattern.

# repos/items.py

class ItemRepo:
    def get(self, item: str) -> Record:
        sql = connect()
        q = sql.query('items').where(item=item)
        record = q.execute()
        return record

    def look_up_price(self, item: str) -> float:
        record = self.get(item)
        price = record['price_cents']
        return price

format_ / transform_

When to use it: When the desire output is a derivative of the inputs, or a metamorphosis such that output is not recognizable from the original form, but only to a connoiseur.

Analogy: When the input is uncooked potatoes and the output is mashed potatoes, you are transforming the raw ingredients into a useful end-product.

Bad

def get_mashed_potato(raw_potato):
    boiled_potato = boil(raw_potato)
    mashed_potato = mash(boiled_potato)
    return mashed_potato

Good

def transform_potato(raw_potato, form_factor):
    result = raw_potato

    if form_factor == 'raw':
        result = raw_potato
    elif form_factor == 'baked':
        result = bake(raw_potato)
    elif form_factor == 'boiled':
        result = boil(raw_potato)
    elif form_factor == 'mashed':
        result = mash(transform_potato(raw_potato, 'boiled'))

    return result

Alternatively, format_potato with the same function body above would work.

Conclusion

Please, for the love of all things proper, think twice before creating another method with the prefix name get_, and use one of the better alternatives: build_, extract_, fetch_, look_up_, retrieve_, transform_.

I promise you – your future self and your teammates will thank you!

Feedback

Agree? Disagree? Love it? Hate it?

Please leave comments or drop me a line!

Back in 2016, I came across this article: https://thecripplegate.com/14-rules-for-being-a-godly-employee/

Recently, I’ve resolved to start my work week by reviewing the 14 rules:

• Rule #1 – Eagerly start the day’s main work
• Rule #2 – Do not murmur at your busyness or the shortness of time but buy up the time all around.
• Rule #3 – Never murmur when correspondence is brought in.
• Rule #4 – Never exaggerate duties by seeming to suffer under the load, but treat all responsibilities as liberty and gladness.
• Rule #5 – Never call attention to crowded work or trivial experiences.
• Rule #6 – Before confrontation or censure, obtain from God a real love for the one at fault. Know the facts; be generous in your judgment. Otherwise, how ineffective, how unintelligible or perhaps provocative your well-intentioned censure may be.
• Rule #7 – Do not believe everything you hear; do not spread gossip.
• Rule #8 – Do not seek praise, gratitude, respect, or regard for past service.
• Rule #9 – Avoid complaining when your advice or opinion is not consulted, or having been consulted, set aside.
• Rule #10 – Never allow yourself to be placed in favorable contrast with anyone.
• Rule #11 – Do not press conversation to your own needs and concerns.
• Rule #12 – Seek no favors, nor sympathies, do not ask for tenderness, but receive what comes.
• Rule #13 – Bear the blame; do not share or transfer it.
• Rule #14 – Give thanks when credit for your own work or idea is given to another.

tl;dr;

isort (PyPI; GitHub) is a wonderful tool that will sort imports in Python automagically, so that you no longer have to either a) ignore eye-sores during code reviews, or b) sound like an angry grandparent asking people to sort/organize imports.

Quick Setup

If you know your away around the *nix environment, these are the abridged instructions:

1. Make the isort binary available somewhere in your path.
2. Install the isort plugin for the editor of your choice.
3. Profit

NOTE: (Optional but recommended) Add a .isort.cfg file to your HOME directory, so that even you are working on a random script or project that doesn’t have one, the powers of isort are still available to you.

Drudgerous Line-by-Line Instructions (or my setup)

1. If you don’t have one already, create a new system-wide Python virtualenv.
   1. The way I’d do that is to do: /path/to/bin/python/virtualenv ~/.venv
2. Install isort.
   1. ~/.venv/bin/pip install isort
   2. (Generic command: /path/to/venv/pip install isort)
3. Add the bin directory of your system-wide virtualenv to your path, or just the select binaries that you want.
   1. I have already added ~/bin/ to my path via bash-ftw, so my preference is to just symlink the specific binaries that I need.
   2. For convenience, I’ve symlinked the following:
      1. ln -s ~/.venv/bin/isort ~/bin/isort
      2. ln -s ~/.venv/bin/python3 ~/bin/python3
      3. ln -s ~/.venv/bin/pip ~/bin/pip
4. Install an isort plugin for your editor (in my case, emacs, The best text editor in the world™).
   1. For emacs only:
      1. For EZMODE™, my dotemacs setup is on GitHub (just git clone, make install, and you’re set!)
      2. Add two lines to your dotemacs (typically ~/.emacs.el or ~/.emacs.elc, or somewhere in your Emacs load path):
         1. (require 'py-isort)
         2. (add-hook 'before-save-hook 'py-isort-before-save)
   2. No longer have to manually organize your Python imports anymore! The isort plugin will do it for you automatically whenever you save your file.

Thank You!

Thanks for reading; now go forth and write some awesome Python code!

Questions, comments, suggestions? Leave a comment or subscribe to the blog for future helpful tips!

In order to learn, there are three kinds of questions to ask: What?, How?, and Why?

Of these, Why? is the best question to ask, and What? is the worst; How? is in the middle but right near the bottom near What?.

The reason Why? is the best question for learning is that it conditions you to go to first principles and learn how to learn.

What? is the absolute worst type of question to ask, because usually the answer to What? is a reference lookup away. A better question to ask is: Where? can I find my own answer to my What? question?

Likewise, How? is rarely a good question to ask. Knowing how to do something is different from being able to do it. The answers to How? questions are best answered by not asking it directly, but rather by finding an expert who already possesses the knowledge of How?, and simply watch that master at work. To achieve this level of mastery takes years upon years of honing one’s craft, and the answer to How? is rarely succinctly communicable, therefore frustrating both the mentor and the apprentice. Instead, just Watch and learn.

Hopefully, at whatever institution you are in, you are surrounded by individuals who have mastered the How? and you can find opportunities to learn from them. If not, there are plentiful and abundant (not to mention, free) resources online to learn How?, such as YouTube. So, really, How? is a pretty bad question to ask since it is actually a series of What? questions in disguise. Instead of asking How?, just observe those who already know how and do, and as you observe, find opportunities to ask them, Why?. And, if they are not available, a still better question is, Where? can I find the resources to learn How?

All too frequent an occurrence in the development lifecycle is doing some work, closing up your laptop/suspending the machine, and coming back to your work hours or days later.

As you try to start up the local webserver or API server, you get cryptic error messages like the following:

• Address already in use
• Another process is already listening on port
• Port xyzw is currently used by another application
• OSError: [Errno 98] Address already in use
• self.socket.bind(self.server_address) blah blah blah blah

And after checking all of your open terminal windows, that you have not in fact any running or killable-processes…

At this point, the n00b naive way to fix this problem is to simply restart your entire machine. To be fair, this technique works almost all of the time, but kills productivity, and forces you to save work-in-progress that’s not at a good stopping point, or worse, accidentally restart without saving your progress.

But, there is a better way.

Let me introduce you to a command:

netstat -tulpn

This command will print out the bound network ports on your machine, and which processes and process ids are running them. To free up the port to be used by your development server once again, simply kill PID, where PID is the process ID.

Now, how to remember this command? I haven’t figured that out yet, nor have I thought of an alias I want to save it to, that is just as memorable. The arguments almost spell out “tulip”–like the flower, except missing the i, and you just add an n to it. Maybe a mnemonic like, “If you fix your network address port in use issue, you will smell the essence of n tulips”?

Whatever you do, netstat -tulpn is now a friend and welcome companion in my software toolbox.