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.
As 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
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
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
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.
Ok, 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
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.