Django, Reading Code for Your New Project

(summary) Djangocon, 2010, by Justin Lilly
watch video

You join a Django project. You would like to contribute code. But how? The codebase is probably more than 10 thousand lines, where do you start? Everyone has similar experience, here are some tips for learning code base. Although we use Django as our example, the concept applies to other projects too.

1. Exploratory code reading: This is often a mandatory step for learning new code base. You need to build certain amount of vocabulary for the code. In Django, for example, if you see someone uses generic view, you should have an idea what generic view is. During code exploration, you also build a level of fuzzy understanding of the code. Don't worry about if you don't fully understand what a method does. You are already building a foundation. Later on, they will just click.
2. Focus, Focus on small parts: Once you built enough vocabulary for the code, you should start focus on certain part of the code. Remember the 80-20 rule? Find something you are interested in, and start focusing on it. Creating a code reading branch, change the variable, do whatever you like. Git log --numstat, if you are using git as your version control, to find what is being modified frequently.
   
3. Debug code, find a ticket: import pdb; pdb.set_trace(). Put that at the place you want the program to stop and trace. In Django, you can put that into the first line of a view function you are interested in. Select one easy ticket in your project, and provide a solution to it. After a ticket or two, you will learn a lot.
4. Read unit tests: it's very very nice if your project has unit test. They are obvious, small, and focusing on a small part of the code base. For example, if you see a test case: test_create_shopping_cart(). You can learn the work flow of creating a shopping cart just by looking at the unit test.
   
5. Views, Models, and Urls: urls.py is the entry point of the code, like the main() in C++. find . -name models.py, use that to find out how your Django "views" all the useful data stored in the db. grep -r 'a_function' . , to see where a_function is called among files.
   
6. Don't go too deep, so ask questions: you don't have to find out all the answer yourself. If you question some part of the code (and you can do better), you can just ask someone who knows it. They can explain why it is implemented this way. Keep in mind the 20-80 rule. You would like to contribute to your team in a week or two.
   

Happy code reading.