Large Django project management

As a freelance developer, I have been involved in numerous Django projects. Moving from smaller projects with only a few apps to complex larger projects is difficult to do. In most cases, I have to get my hands dirty, work on a few bug fixes to familiarize myself with the codebase. Before that though, it’s important to set the proper groundwork by establishing expectations with the client and analyzing the code from a higher level.

Obviously, the steps you take will vary greatly depending on what you’re hired to do (i.e., adding features, fixing bugs, creating documentation, etc.) as well as how the Django project itself is setup. There’s numerous ways to structure a project, which can make it difficult at first to understand the logic.

When approaching a project, I focus on the following areas to quickly get up to speed with the codebase and determine the unknowns.

Initial client communication

1. Describe the type of work needed and the priority?
2. Will I have access to the current or former developer(s)?
3. How will my role coincide with the current developers? How will I communicate with them?
4. Who am I directly reporting to?
5. Who makes architectural/design decisions?

Resist the temptation to set any expectations during the initial call with regard to development time and basic price points. Take the time to go over the codebase first to see how complex the project is and to determine how long it will take for you to become familiar with their specific project setup.

If both parties decide to move forward, make sure you request login credentials for the superuser, shell access, and their repository. Ideally, you will want to obtain these credentials for the development, staging, and production environments.

Code Review

Once you have cloned their repository, and begin the first pass of their codebase-

1. Take note of important files/directories (i.e., manage.py, settings.py, urls.py)
2. Determine the relationship between urls, views, and templates (parent vs. child templates). I use an Excel doc to track.
3. How is the project organized? Are best practices followed? Are apps broken up by specific functions?
4. Which installed applications are core to the projects infrastructure?
5. Is there a local settings file? How big is it? The bigger the file, the more that the development environment is going to differ from production. Keep this in mind when testing.

Finally, when going through the code review, address these issues:

1. Is there a requirements.txt file. No? Do a pip freeze > requirements.txt. Familiarize yourself with the project’s dependencies. Have you worked with a specific third-party application before? If not, go read the documentation.
2. Which Django version are they using? Could there possibly be any issues with their current version and the installed applications?
3. Are there any scheduled tasks (cron jobs)?
4. What type of version control system do they have in place? Are they using it correctly? What are their processes?
5. Are unit tests in place? If so, what are they testing – and when? What about integration testing? Are any tests failing?
6. Is South installed?
7. Are they using a virtualenv?
8. Have they separated config from the actual code?
9. Is Fabric used for deployment?
10. How well is the code documented? Is there inline documentation within the codebase itself? How well do they document their version control commits?
11. Can you get a basic sense of their standards, configurations, and/or naming conventions (variables, functions, classes, etc)?
12. When/who ships code? What’s the process?

Next steps

I focus my code review on whether I can (a) get an overall sense of the project (e.g., what are they trying to do), and (b) whether I am qualified to take on the project in the first place. If the project has too many unique/non-standard components, it may not be worth taking on.

In the end, all apps have a models.py and a views.py file. Larger projects should also include the urls.py file and tests.py in each application. If this is not the case, it will take longer to document.

Documentation and testing are big red flags. I tend to avoid projects where testing and/or proper documentation are not priorities.

Start at a high-level, reviewing the URLconfs and documenting the basic logic/structure/workflow, then work your way down through the templates, unittests, views, and finally the models. Models tend to hold the most complexity, so having a basic understanding of the project first, will help you greatly when you encounter the models.

Document all unknowns. Ask yourself what else you need to do or know before you can make a reasonable decision about whether you can complete the job, as well as the how long it will take.

Use django-graphviz to quickly visualize the database schema and django-template-analyzer to establish the relationship between parent and child templates.

Be honest and direct with your next communication with the client. Don’t be afraid to pass on a project. There’s plenty of work out there. Focus on the projects that you can reasonably handle and, above all, make sure you feel comfortable with not only the codebase but your employers as well. Good luck.

Written by Michael Herman, hacker at Gun.io and co-founder of Real Python.