Adrian recently corrected some of my docstring additions [1][2], and I
am posting this to the list so that we can get an official stance on the
matter. I also suggest we add the decision to the "Coding style"
section of the "Contributing" documentation for consistency of future
patches, since AFAIK the subject is not mentioned in PEP 8 [3] or PEP
257 [4].
Adrian seems to favor "action words", whereas Guido mentions the
following in his Python Style Guide [3]:
The doc string is a phrase ending in a period. It prescribes the
function's effect as a command ("Do this", "Return that"), not as a
description: e.g. don't write "Returns the pathname ...".
Adrian, which BDFL do we follow :)
[1] http://code.djangoproject.com/changeset/5756
[2] http://code.djangoproject.com/changeset/5758
[3] http://www.python.org/dev/peps/pep-0008/
[4] http://www.python.org/dev/peps/pep-0257/
[5] http://www.python.org/doc/essays/styleguide.html
Gary
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django developers" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-developers?hl=en
-~----------~----~----~----~------~----~------~--~---
