Tutorial on transforming a complex, linear Python script into a modular, easier-to-maintain application.
Python Makefile
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Draw the rest of the owl


"Complexity kills." ~ Ray Ozzie

"The art of simplicity is a puzzle of complexity." ~ Douglas Horton

"...you're not refactoring; you're just changing shit." ~ Hamlet D'Arcy


This repo contains code samples demonstrating how to transform a complex, linear script into a modular, easier-to-maintain package. The code is a teaching aide used in Python classes at NICAR 2014 and NICAR 2015, but can also work as a stand-alone tutorial (check out our main documentation site).

The tutorial uses a small, fake set of election results for demonstration purposes.

Project code evolves through four phases, each contained in a numbered elex directory. Below are descriptions of each phase, along with related questions and exercises that anticipate the next phase or set of skills.

The goal is to demonstrate how to use Python functions, modules, packages and classes to organize code more effectively. We also introduce unit testing as a strategy for writing programs that you can update with confidence. The overarching theme: As an application or program grows in size, writing readable code with tests can help tame complexity and keep you sane.

Wondering how to use this tutorial or why the hell we called it refactoring101? The FAQ has answers to these and sundry other questions. Also, check out the Resources page for wisdom from our tribal elders.