From Atul Gawande’s Checklist Manifesto[0]:

Good checklists, on the other hand are precise. They are efficient, to the point, and easy to use even in the most difficult situations. They do not try to spell out everything–a checklist cannot fly a plane. Instead, they provide reminders of only the most critical and important steps–the ones that even the highly skilled professional using them could miss. Good checklists are, above all, practical.

Gawande relies heavily on the story of pilots who use checklists to avoid avoidable errors, unforced errors, the kind that we miss because they’re not obvious, we take them for granted, or we get a little arrogant (this has never happened to me).

Now, there’s a lot that checklists can’t do - they’ve probably been a bit oversold - but that doesn’t detract from their benefits. They won’t skyrocket you to success, but they may help you avoid shooting yourself in the foot. And this happens to be true in software, too, including Django projects!

Your excitement is palpable.

These checklists apply to Django projects on the whole, the development process, and Django app structures. Checklists in your Django project help protect against new errors, against long onboarding times for new developers, and even commonly acceptable practices which can cause development friction. So what do they look like?

When we conduct Django code reviews[1] we start with a basic checklist to identify a baseline:

• The project uses version control (preferably Git or Mercurial)
• The project has a README explaining how to install and run
• The project has one or more requirements files
• The requirement versions are “pinned”
• The project can be successfully installed locally
• The project (and related services) can be successfully run locally
• The project has tests
• The tests can be run
• The test suite runs without failures or errors This is what you could call table stakes. This is the “can someone else start up the project and run it” checklist.

There’s also the automation checklist.

• Are tests run every time code is pushed to the remote source code repository?
• Are language linters run with tests (for checking style and static analysis)?
• Is promotion to master guarded by successful build?
• Is deployment scripted from a single command?
• Is deployment automated by a build system? And of course Django specific checklists:
• Models explicitly specify table names
• ModelForms specify fields rather than excluded fields
• Model migrations are named descriptively
• DB querying uses named queryset methods (vs. ad hoc filtering or non-query filtering)
• Form submission validation is handled within form classes
• Multi-method views are class-based[2][3] There’s more than just these, both list items and checklists alike, but this should be enough to give you the flavor for what they do. Even if you’re the only developer on the project you own they can help you to ensure you’re doing the right thing. Think of them like regression tests “for everything else”. They keep you from taking [popular and acceptable!] shortcuts (“let’s just exclude these fields”, “oh it’s used once we’ll just write this big filter expression in the view”) and banking problems for yourself in the future.

Interested in more Django checklists to keep your project on the straight and narrow? Just exercise your right to reply…

Always checked offedly yours,
Ben

[0] https://en.wikipedia.org/wiki/The_Checklist_Manifesto
[1] The Django Code Review: https://wellfire.co/services/django-code-review/
[2] In many cases functional views are better than class based views, however the non-trivial logic of handling more than one type of HTTP request obviates the benefits of functional views in all but the simplest cases.
[3] Having not actually tried using it yet, this flake8 plugin looks promising: https://github.com/rocioar/flake8-django

More like this

• Leverage points in Django development (This Old Pony #67)
• Breaking out your Django app for great good (This Old Pony #65)