How to dive into another team’s Django code

I’m starting to learn my way around another team’s Django project.

They started from yet another team’s code base, and extensively modified it over the last ~1.5 years. It’s code for a large commercial site, which I hope to use to build an even larger commercial site having needs similar to, but different from, theirs.

My immediate goals are to figure out what code changes the new site will require, and some project logistics.  Source pool management will be the trickiest of these — do we share, partially share, use separate pools with periodic merges, or cleave off and stay forever separate?

I tend to approach design holistically.  But sometimes, like now, I have to force myself to use a different approach in order to get the best results. Here’s my approach for jumping head first into another team’s pool.

Ask a good friend to tell me the obvious.  For this pool reconnoiter and analysis, I should focus on one area at a time, rely on malleable assumptions about unexplored areas, and be content with gradually building a knowledge base.  And so I need to ditch my preferred, “chew on and digest it all simultaneously,” approach.

Therefore, the first task is to put my head in an entirely different mode!  For me, what works well is to share my concerns with a good friend, and count on him to remind me of the obvious.  (Think of this as a metaphorical cuff on the head.)

I did this last week, and my wise friend didn’t disappoint. “Just break the problem down into smaller parts and then attack each one,” says the wise friend…

To this, you might say, Well duh!  Yes, I already knew this. But for some deep emotional reason maybe stemming from never getting enough toys as a child, I needed to hear him say it.  And it worked — my head has switched modes.  (He’s uttered other pearls of wisdom in the past, like, “Take a deep breath and back away from the keyboard,” and, “You’re a freak of nature.”  He hasn’t been wrong yet.)

Understand all the settings.py variants.  Settings.py is a Django project’s master control.  It defines important characteristics about databases, caches, sessions, etc., which anchor the project’s execution environment.  So I choose to start my pool exploration here.  

“Understand” doesn’t mean, “skim.”  It means I’ll totally grok what’s in settings.py, and any dev or test variants thereof.  If I find something I haven’t seen before, I stop and learn it.  

By understanding how the team created their development environment, I’ll understand what I need to do to get their code running on my dev box.

Understand the URL dispatching.  I investigate URL dispatcher files next.  Again, I don’t glance or skim, but I really understand what’s going on here.

This will tell me which source pool directories are used, and which can be ignored.  And how syndication feeds are handled. And the view arguments’ code conventions, and (hopefully) how the code is organized.

In this situation, there’s original code, modified original code, and superseded code.  The URL dispatching files will map this universe.  If the mapping gets too complicated, I might color-code a source tree listing with a highlighter.

Find and read the model files.  I next figure out where all the active and used (vs. historical, archive, or oops we neglected to delete that one) model files live, and read them.  If I don’t recognize a field type or option, I stop and understand it.  And I scrutinize all the custom manager methods.

If the number of tables isn’t stratospheric, I’ll make a schema diagram of the project’s models — DjangoGraphViz is good for this.

Run the project on my laptop.  The last step is to run the project up on my laptop, using their developer settings files, and play with it so I understand the views’ functionality for the user.

After all of this, I’ll be ready to think about the changes my project needs, different middleware or contrib packages, source pool management, etc.

How do you learn your way around an alien Django project?  I’d like to hear other ways of doing this.