Designing project layouts that aren't terrible

Making the New Guy’s First Week Less Painful

The most awkward part of getting a new developer on a project is that first week (or so) where he or she needs to get familiar with the code, figure out how to run things, and generally get a feel for how the project is laid out.

This is always an anxious period of time for me (both as the new developer and as the one trying on bring someone onboard) because there’s not really a good way to do it.

I was recently at a meetup session of NOVA-Python, the Northern Virginia Python Users Group. The organizer, Ryan Day, had some good tips on building out a project structure that will make it easier for new developers on a project to jump in.

Two things in particular stood out as being particularly useful and I wanted to expand on them. This is the first of two entries.

The Config File as a Learning Experience

Maintaining configuration files kind of sucks. As developers, we try to not hardcode values that need to change and they inevitably wind up in some kind of external configuration. The problem is that now we have a config file that we check into version control and have to remember to change the values in each time we deploy code to a new environment.

If you’re like most developers, you probably populate a copy of the configuration file(s) with some sane values that work for 75% of the development team and hope that no one shows up with a different set up.

When buidling Flask apps, I typically have a config.py file that looks something like this:

DB_SERVER = 'localhost'
DB_PORT = 5432
DB_NAME = 'flaskdb'
DB_USER = 'austin'
DB_PASSWORD = 'p0stgres'

# more config ...

… and somewhere in my Flask app, I just read in that file:

app.config.from_pyfile('config.py')

I’m here to argue that checking things in like this is an anti-pattern. Here’s my better idea: create a config.sample.py file that doesn’t contain real values, but walks the new developer through the whole thing.

# The application requires a database connection
# See the db-setup.py script for setting one up.
# Change these values to match your development database.
# Need help setting up the database? Check out DATABASE.md.

DB_SERVER = 'db-hostname-here'
DB_PORT = 5432
DB_NAME = 'dev-db-name-here'
DB_USER = 'flaskapp'
DB_PASSWORD = 'change-this'

# more config ...

The idea is that the new developer should copy this into config.py and change the values while reading it over. Without having an actual config.py checked into version control, the new developer has to spend a few minutes reading over the configuration file.

Now to make this even more developer friendly, throw a message in the error that will be called in case they forget to set up their config.

try:
    app.config.from_pyfile('config.py')
except:
    print 'Error loading config.py. Did you remember to copy config.sample.py?'
    sys.exit(1)

Conclusion

So as end result, you have an extra step toward getting your application up and running. For small apps, this might be kind of annoying, but for larger apps that have a lot of configuration, this can help the new guy.

Starting this thing over

My name is Austin Keeley. I’m a software engineer.

I graduated from James Madison University with a BS in Computer Science. I later completed my MS in Computer Science from The Johns Hopkins University. I’ve been developing software professionally for about 8 years.

By my own count, this is the third time I’ve re-launched this blog. Usually I plan on writing a lot of really fun articles, but then it gets neglected and I just kind of quit and I wonder why I even bothered. But this time it’s different! No really! I’m at a really good place in my career as a software developer and I feel like I can finally contribute some knowledge back into the culture.