A revelation came to me a few years ago when I read an article suggesting that arguing is not about truth. Humans evolved our talent for arguing in order to win allies:

Now some researchers are suggesting that reason evolved for a completely different purpose: to win arguments. Rationality, by this yardstick (and irrationality too, but we’ll get to that) is nothing more or less than a servant of the hard-wired compulsion to triumph in the debating arena. According to this view, bias, lack of logic and other supposed flaws that pollute the stream of reason are instead social adaptations that enable one group to persuade (and defeat) another.

I have noticed this behavior at work. I start a discussion. The discussion turns into an argument. I sense myself becoming defensive. Suddenly I am justifying my own existence and abilities. Opposing arguments are coming into my brain, almost reflexively, outside of my own control. It is like my subconcious is feeding me ammunition for a war. I notice the person I am arguing with doing the same thing, and now I am locked into a hard fight that has strayed far from the goal of figuring out the best solution for the team.

These kind of arguments are poison. It gets even worse in a group meeting when I feel like I am defending my competence in front of an audience.

So what to do instead? Here is a “magic” technique I have discovered for resolving disputes in a productive manner:

Bring up your concern in a non-accusatory way.

Here is a bad way to voice your concern:

Why did you use framework X for this project? I think framework Y would be better.

Here is a good way:

Do you have strong opinions about using framework X for this project? I’m thinking that using framework Y might have some advantages.

The first phrasing forces the other person into a defensive mode. Even if they did not have strong opinions about using framework X in the first place, their subconcious will rally to meet the threat and start generating rationalizations on the spot. The person will feel an instinct to justify their intelligence and decision-making abilities.

The second phrasing allows for an easy out – they can just say they do not have a strong opinion. Nor does the phrasing challenge their abilities, so you avoid putting them on defense.

As soon you sense defensiveness, stop and change tactics.

Once I start discussing the pros and cons of X versus Y, the discussion still might become heated. As I sense myself or my teammate becoming reflexively defensive, I back off. The argument has changed tone and will no longer be productive.

Huddle together and collaboratively examine options.

When the argument becomes heated, I stop and say, “OK, this debate is getting too complex for me to keep straight in my head. Let’s huddle.” We both sit in front of the same computer screen and I open up a text editor. At the top of the document I write the problem that we are trying to solve. For example, “Problem: our web application only supports 1,000 concurrent users and we need to support 10,000”. Then I say, “Let’s brainstorm. What are the ways we can solve this problem?” We enter the options we were arguing about previously, but also generate new ideas. Then under each possible solution, we each list pros and cons. For each con, we go one level deeper and offer ideas on how serious the con is, and how the con could be worked around.

The key is that we jointly create pros and cons for all solutions. In this way, it is no longer “My solution versus their solution.” We both own the solutions, and neither of us risks losing face.

At the end of the brainstorm we have quite a long outline. Sometimes the answer is obvious to both of us once we have enumerated the pros and cons. Sometimes the right answer hinges upon a critical assumption. The next step might be, “Let’s spend a day and run a trial that will test our performance assumptions if we choose option A. If performance is sufficient, we will do option A.” Other times we might remain conflicted.

Search your mind for data points you have not shared.

Sometimes during an argument, I pause, step back, and think, “What is the sticking point of our dispute? Why am I seeing things in a different way than my colleague?” I may realize that I have some unspoken data point in the back of my head that I am relying on. Perhaps I recently talked with a friend about why framework Y was so cool. Perhaps I was on a forum where I saw that a bunch of people were looking to work at a company using framework Y, and I had some vision that we could use Framework Y as a way to attract top talent. It is surprising how often a dispute arises from one person having data points they are not sharing. The solution is simple: Take a moment, think deeply about why you feel the way you do, and share your data points.

Making the call

I have found that after using the huddle-and-collaborate technique, about 90% of conflicts simply melt away (hence me calling the technique “magic” – the dispute simply disappears). The original dispute usually happened because one person had data, perspectives, or work-arounds that the other person was not aware of. Once the pros and cons are visible to all, the right answer is usually obvious.

What about the other 10% of the time when you are still at odds? When in doubt, defer to the person who is actually doing the work. The person doing the work has their head in the problem and is in a better place to make a decision. Furthermore, if you pull rank and then turn out to be wrong, you will crush their morale. Whereas if they make the call, and turn out to be wrong, they will put in the extra effort to make amends. They will learn from the mistake and develop better judgement in the future. Do not compromise for the sake of compromise, as that makes no one happy and only leads to mediocrity.

The cases when you need to pull rank are when 1) being wrong incurs huge strategic costs to the business or 2) you sense that interests might not be aligned between the employee and the company. For example, in software engineering the employee has a personal incentive to try new frameworks and tools. New tools are fun and build the résumé. The company has an incentive to use tried-and-true tools. The company wishes to standardize across teams so that employees spend less time learning and more time doing. So if you sense the engineer wants to try a new tool purely for the sake of learning something new, then you might have to say no.¹

I hope you find this technique useful and good luck with your next argument!

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):
    try:
        self.dispatch(task)
        succes_callback()
    except Exception, e:
        error_callback(e)
    
# 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):
    ...

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 is a
# 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 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 username.  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.

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', 'rb')
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 IndexError("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 IndexError("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).

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"

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.

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.

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.

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.

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.