"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 was written as a reference for the Python: Beyond the Basics class at NICAR 2014, 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.