Chicken Scratches

Django: Eddie’s Practices #1: Choose Names Carefully

Why “Eddie’s Practices?”

Django has become one of the more popular web frameworks out there. I have been lucky enough to have worked with it for many years, starting in its early beta stages. I’ve used it to create many web applications on my own, and I’ve worked on many apps that were originally created by others.

django-logo-positiveAs in most development environments, there are certain common issues that pop up again and again. Over the years, through trial and error, talking to other developers, and a lot of hard thinking, I’ve come up with some general approaches to many of these issues.

I have gotten a great response to my previous posts about Django, so I decided to create a new series of posts, dealing with these tips and techniques. I wouldn’t have the hubris to call these “best practices,” because that would imply that my way is best for all developers. So I’ll just go with “Eddie’s Practices.” These are things that work for me, things I wish people had told me when I was starting out. I hope they work for you, too. Mileage may vary, as they say.

Tip #1: Think hard about what to name your project and your app.

We’ll start with a basic one, but one that seems to come up over and over. When you get started with Django, you create a “project,” and then within that project you create an “app.” You need to come up with names for both of them. This may seem a trivial point – surely an app by any other name would be just as enterprisy. But it can affect your future development in unexpected ways.

For example, say you want to create a website for playing poker. Not a very far-fetched idea – there are a couple sites like that out there. So you check the Django getting started guide, and run the command to create the project:

~/src>django-admin.py startproject poker

Fair enough. It makes sense to call your poker project poker. But now, you need to create an app as well. What do you call that? Well, we can’t use poker, as the following shows:

~/src/poker>python manage.py startapp poker
Error: You cannot create an app with the same name ('poker') as your project.

Hmm, you think. Maybe I can be clever! So you decide to name the app “game.” That way, you can refer to it as poker.game. Brilliant! It’s a poker game!

Not so fast.

Oh sure, it seems fine for a while. You come up with a clever marketing strategy, you launch it at zoombidingle.net, you advertise it, you even start to get some users. After a while, you decide business is going well enough that you want to expand. Poker’s great and all, but what people are really clamoring for these days is dominoes. The wave of domino-mania that is sweeping the nation is unprecedented. You don’t want to miss out on your piece of the domino-pie, so you decide to create a Dominoes app.

As a smart business person, you see it makes sense to leverage your existing user base and just add on to Zoombidingle. You can even let your users use their existing virtual poker chips to buy into the domino tournament. Fine: cd into your project directory and start typing:

~/src/poker>python manage.py startapp ...

Now you’re stuck.

It obviously makes sense to call the new app something like “dominoes,” but you have a nightmarish vision of having to type poker.dominoes all over your code. Besides sounding vaguely obscene (“I don’t even know ‘er!”), it doesn’t accurately describe the code’s hierarchy. Add to that, you still have poker.game, but isn’t dominoes a game, too?

So you rename things. You change your project name from poker to games. (You don’t go with zoombidingle because you don’t want to link the marketing decision of the site name with the codebase.) You change your old app name from game to poker. You do a bunch of grepping through the code base, hoping you catch every reference to those names, and hoping you don’t forget which poker is which and don’t confuse game with games. You update your web server configuration to point to the new directories. You deal with the errors Subversion always seems to give when you rename a directory, and voila! You have a new project hierarchy, and you can happily create your dominoes app and go on your merry way.

025_352Ok, so is it a huge deal to have to rename things? Maybe not, but it’s two or three hours of your time you could be using to write fresh code or catch up on Glee. It just makes sense to pick the right name in the first place.

And I know I’m not the only one who has run into this issue. I have taken over a development project where the “project” was called (let’s say) fooblygoop, which was the name of the website. They apparently were not feeling very creative, so the “app” got named fooblygoop.fooblygoopapp. Bleah!

So now we come to a general rule of thumb. Eddie’s Practice #1:

Think specific for the app name, think general for the project name.

The important thing to remember is that you may end up using the app in another project, and you may end up adding more apps to the current project. In fact, in my experience, this almost always happens. Even when you don’t anticipate reuse, you’ll often be surprised later to find yourself recycling an old app.

For the poker example, poker would have worked as the app name, or maybe something even more specific, like holdem if your site is a Texas Hold’em site. Then you could even market the app as a standalone plugin for third-party web sites.

For the project name, think about how you might possible expand the project in the future. games is nice and general. Or even funstuff if you’re feeling whimsical.

Yes, this is a simple tip, but one that is well worth keeping in mind. It could save you a few hours and a few aspirins.

Stay tuned for more of these tips. They’ll get more in depth and technical as they go along. And please let me know in the comment section if you find this helpful or you have anything you want to add.

Track comments by RSS

4 Responses to “Django: Eddie’s Practices #1: Choose Names Carefully”

  1. Scott says:

    I’m just learning Django and Python, but went around in circles for a bit with this same question last week. I’m developing a site for creating and managing workout and exercise plans, so you can track your fitness progress each day.

    I ended up naming the project the same as the domain name that it will be hosted on (something like ‘ironmanfitness’), and naming my first app ‘workouts’, which contains all the models and logic specific for managing workouts (like different exercises and all that). I figured that down the road, I’ll develop maybe a ‘profile’ app for user management, and whatever else I come up with.

    As near as I could tell from looking at Django for a day or so, apps seem analogous to modules or library assemblies in something like .NET from structural standpoint. Is that about right?

    Thanks for the useful post!

  2. Scott, I would agree with your analogy to the extent that an app is a potentially-reusable component. Like a module or library, it can interact with other apps and with the core system.

    We should be careful with such analogies, though, because they don’t always capture the whole picture, including templates that may need creating and so on.

  3. Aredhel says:

    Hello,
    nice post. I’d like to add one thing to this – try to come up with different names than Django’s apps. I remember having some problems with my authentication module extension because it was named “auth” as is the Django module (if I remember correctly, it’s been a while :)).
    I’m looking forward for the next tips.

  4. Aram says:

    I’m a bit confused over why the name of the project is a concern at all. Of the many many Django websites I’ve worked on, not a single one had any reference to the project name in the source, and you could rename the project folder with no ill effects.

    Since the apps live in the same directory as `manage.py`, they are always importable from the top-level (i.e. you can do `from app_name.models import MyModel` in any app). In fact, they *must* be, for Django to work correctly. Even the ROOT_URLCONF setting, which is auto-set by Django to ‘project_name.urls’ can safely be set to just ‘urls’. If you have apps in unorthodox locations, just add their parent dirs using `sys.path.insert()` in your settings.

    Taking it a step further, projects should also be completely agnostic to the path they live in. You can have something like `ABSOLUTE_PROJECT_PATH =os.path.abspath(os.path.dirname(__file__))` in your settings file, and set all other paths (e.g. media or static) relative to that using `os.path.join()`. All Django projects I’ve worked on can be checked out into any given directory, and will be able to run after only five commands:

    * mkvirtualenv some_name –no-site-packages
    * pip install -r requirements.txt
    * cp local_settings.dev.py local_settings.py
    * ./manage.py syncdb
    * ./manage.py migrate (if using South)

Leave a Reply