gtg-user team mailing list archive

[Jonathan Lange <jml@xxxxxxxxx>]

Hello,

I've been looking around the GTG codebase a bit now, trying to see how
things are laid out.

One thing I've noticed is that a lot of functions have comments above
them, rather than docstrings inside them. For example:

    #Return true is the task has parent
    #If tag is provided, return True only
    #if the parent has this particular tag
    def has_parents(self,tag=None):
        #The "all tag" argument
        if tag and len(self.parents)!=0 :
            # ...
        return to_return

Most of the time, you see documentation written like:

    def has_parents(self, tag=None):
        """Does the task have parents?

        Return True if the task has parent. If 'tag' is provided, return True
        only if the parent has this particular tag.
        """
        #The "all tag" argument
        if tag and len(self.parents)!=0 :
            # ...
        return to_return

Is there a reason for using the "comment before function" style? Would
you mind to much if I submit patches that change the comments into
docstrings whenever I happen to be touching that part of the code?

See also http://www.python.org/dev/peps/pep-0257/ and
http://www.python.org/dev/peps/pep-0008/.

jml