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 variants. 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, 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.


4 thoughts on “How to dive into another team’s Django code

  1. I tend to start with a project’s models first (using INSTALLED_APPS as a guide). In most projects the models are centric: they are the first things written and the things most often referred to. Knowing the models a little bit better can give you subtle clues when looking at the URLs such “why isn’t a generic view used here”. In simple projects there are nothing but smartly applied generic views and knowing the models is just about all you really need.

  2. Hi,

    I’m in a similar situation at the moment. I was employed by a company who outsourced the project I’m working on originally, and then had to pull it back under their control after some terrible project management (and lack of basic competence) for the sub contractors.

    We face a codebase which is riddled with inconsistency and doesn’t really make any use of the best bits of django. There have been several times when this has really screwed me for a couple of hours where I’d be trying to grok what was happening and run into a brick wall…

    One of the best was where some js wasn’t loading. I couldn’t even see where it was being put into the tamplate (you’d assume there’d be a tag somewhere wouldn’t you..). What there actually was was something like this:
    {% include yahoo.html %}
    the contents of which were:
    <script src=”{{ YUI_URL }}/path/to.js” …

    And this wasn’t even in the head element!! The {{ YUI_URL }} was determined by means of a context processor, depending on whether we were serving it locally or from yahoo.

    So at this point I feel that I can’t trust ANY of the app and therefore there’s no point in debugging where I can make any assumptions.

    Anyhoo, rant over, life sucks etc etc 😉

  3. If possible, I generally ask someone that’s already familiar with the codebase for pointers. 😉

  4. @Jeremy:

    I completely agree.

    I didn’t include that step, because, well, I take it as a given. Just like powering-on my laptop and logging in. But since it’s part of the overall process, I can see that I should have included it.

    So, yes, that happens right before or after, “Ask a good friend to tell me the obvious.”

    In this case, I did that. The other team’s leader was very helpful, and probably spent too much time with me for his own good 🙂 in explaining what’s where. AFAICT, the other time is pure Aces, and I’m going to have to run hard to keep up with them. 😉

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.