Why you need help text in your objects

Adding docstrings can make your life much easier in the long run.  They can also help anyone that might be looking at your code after you.

Here is a simple example of a model with a doc string:

class total_clicks(models.Model):
“”"Here are the total clicks that have come from this user.
“”"
user = models.ForeignKey(User, unique=True, blank=False, null=False)
total = models.IntegerField(blank=False, null=True)

class Meta:
verbose_name_plural = “total clicks”

def __unicode__(self):
return u”%s” % self.user

The help text defined in the model looks like this: (yes this is crap text, but I am a dummy..  you could put something more meaningful here)

“”"Here are the total clicks that have come from this user.
“”"

Not only can I see the helper text in the code, but when I use help() or .__doc__ on that object I can information about the model.

Example:

>>> from reports.models import total_clicks
>>> total_clicks.__doc__
‘Here are the total clicks that have come from this user.\n    ‘
>>> help(total_clicks)

class total_clicks(django.db.models.base.Model)
|  Here are the total clicks that have come from this user.
|
|  Method resolution order:
|      total_clicks
|      django.db.models.base.Model
|      __builtin__.object
|
|  Methods defined here:
|
|  __unicode__(self)
|
|  ———————————————————————-
|  Data descriptors defined here:
|
|  user
|
|  ———————————————————————-
|  Data and other attributes defined here:
|
|  DoesNotExist = <class ‘scaffiliate.reports.models.DoesNotExist’>
|
|
|  MultipleObjectsReturned = <class ‘scaffiliate.reports.models.MultipleO…
|
|
|  objects = <django.db.models.manager.Manager object at 0x10e7410>
|
|  ———————————————————————-
|  Methods inherited from django.db.models.base.Model:
|
|  __eq__(self, other)
|
|  __hash__(self)
|
|  __init__(self, *args, **kwargs)
|
|  __ne__(self, other)
|
|  __repr__(self)
|
|  __str__(self)
|
|  delete(self)
|
|  save(self, force_insert=False, force_update=False)
|      Saves the current instance. Override this in a subclass if you want to
|      control the saving process.
|
|      The ‘force_insert’ and ‘force_update’ parameters can be used to insist
|      that the “save” must be an SQL insert or update (or equivalent for
|      non-SQL backends), respectively. Normally, they should not be set.
|
|  save_base(self, raw=False, cls=None, force_insert=False, force_update=False)
|      Does the heavy-lifting involved in saving. Subclasses shouldn’t need to
|      override this method. It’s separate from save() in order to hide the
|      need for overrides of save() to pass around internal-only parameters
|      (‘raw’ and ‘cls’).
|
|  serializable_value(self, field_name)
|      Returns the value of the field name for this instance. If the field is
|      a foreign key, returns the id value, instead of the object. If there’s
|      no Field object with this name on the model, the model attribute’s
|      value is returned directly.
|
|      Used to serialize a field’s value (in the serializer, or form output,
|      for example). Normally, you would just access the attribute directly
|      and not use this method.
|
|  ———————————————————————-
|  Data descriptors inherited from django.db.models.base.Model:
|
|  __dict__
|      dictionary for instance variables (if defined)
|
|  __weakref__
|      list of weak references to the object (if defined)
|
|  pk
|
|  ———————————————————————-
|  Data and other attributes inherited from django.db.models.base.Model:
|
|  __metaclass__ = <class ‘django.db.models.base.ModelBase’>
|      Metaclass for all models.

Now imagine all the time you could save if you actually had some helpful text in there that told you how you needed to interact with the model.