2011-03-28
Why you should avoid 'from module import whatever'
Every so often I get to re-learn vaguely painful lessons.
For whatever reason, Django has a distinct coding style, as expressed
in things like their tutorial documentation. When I wrote my Django
application recently I generally followed this
style, partly because I took bits and pieces straight from the tutorial
(because it was the easy approach). One part of the Django style is a
heavy use of 'from module import SomeThing', or even 'from module
import *', and I copied this for my own code. Everything worked fine
and it certainly was convenient.
Then somewhat later I went back to the code and found myself staring at
a section of it, wondering just where a particular function came from.
Fortunately, context and naming made it fairly obvious that it wasn't
a standard Django function, but I had to do a file search to determine
whether it was from my views.py or my models.py.
(And I had it easy, since I only had two files that it could have come from.)
In a nutshell, this is why namespace-less imports are bad: they hide
where names come from, stripping them of context. Context is a good
thing, because us fallible humans can only hold so many things in our
head; the more explicit context, the less we have to keep track of
ourselves. Even partial module names helps (where you do 'from module
import dog' and then use 'dog.SomeThing'); if nothing else, it tells
you that this particular name doesn't come from the current file and it
gives you an idea of where to start looking.
(In the best case the partial module name is both unique and distinctive, so it generally gives you the full context on the spot.)
Some people will object that specifying even a partial module name results in too much typing. My response is that this just means you need shorter names.
(Yes, coming up with good short names are hard. No one said API design was easy.)
PS: I don't particularly fault Django for this particular element of their style; it's consistent and fits their overall goals and does save a certain amount of more or less make-work.
The problem with contributing documentation to projects
Every so often, a well intentioned person will suggest that you should help out open source projects by contributing documentation (there are several variants of how this suggestion is made, but this is what all of them boil down to). The problem is that this is much harder to do than you might think, especially for significant technical documentation like API details.
Setting aside all of the other difficulties of creating documentation, the core issue is that official documentation must above all be accurate. It is not enough to describe something that works (for you); you need to be correct about what you are describing and how it operates, you need to be complete, and you need to be describing the correct way to do something (instead of, say, an odd hackish workaround that you stumbled over or an internal interface). In order to produce this sort of accurate documentation, you generally need to be an expert with a deep understanding of the code, the history, and the philosophy of the project.
(An additional issue is that you generally need to be an expert with the current bleeding edge development version, because this is generally what the project is working on. Any expertise with older released versions is much less useful; even if the project is going to maintain them for some time, projects are generally not enthused about having older versions be better documented than new ones.)
Trying to contribute documentation that is not necessarily accurate is just as dangerous as other overly-detailed bug reports and patches, and for the same reasons. At a minimum, you force a project expert to double-check your documentation (and even for an expert this may take work and investigation). At the worst, your inaccurate work is good enough to fool people on superficial examination and is accepted into the project's documentation, where its subtle problems may fester for some time.
By contrast, carrying on on a blog to note down some things you've worked out is much easier. You don't need to be complete, and no one with any sense expects a third-party blog entry to be accurate in the way that the official documentation is.