What is the proper way to comment functions in python?

Question

Is there a generally accepted way to do this? Is this acceptable:

#########################################################
# Create a new user
#########################################################
def add(self):

Answer 1

Read about using docstrings in your python code.

As per the Python Docstring Conventions:

The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

There will be no golden rule, but rather provide comments that mean something to the other developers on your team (if you have one) or even to yourself when you come back to it six months down the road.

Answer 2

The correct way to do it is to provide a docstring. That way, help(add) will also spit out your comment.

def add(self):
"""Create a new user.
Line 2 of comment...
And so on... """

That's three double quotes to open the comment and another three double quotes to end it.

See: http://diveintopython.org/getting_to_know_python/documenting_functions.html

Answer 3

I would go for a documentation practice that integrates with a Documentation tool such as Sphinx.

The first step is to use a docstring:

def add(self):
 """ Method which adds stuff
 """

Answer 4

Use a docstring.

Answer 5

Use a docstring, as others have already written.

You can even go one step further and add a doctest to your docstring, making automated testing of your functions a snap.

Answer 6

Oh boy! Consider a can of worms opened :)

The principles of good commenting are fairly subjective, but here are some guidlines:

• Function comments should describe the intent of a function, not the implementation
• Outline any assumptions that your function makes with regards to system state. If it uses any global variables (tsk, tsk), list those.
• Watch out for excessive ASCII Art. Having long strings of hashes may seem to make the comments easier to read, but they can be annoying to deal with when comments change
• Take advantage of language features that provide 'auto documentation', i.e. docstrings in Python, POD in Perl, Javadoc in Java

Answer 7

I would go a step further than just saying "use a docstring". Pick a documentation generation tool, such as pydoc or epydoc (I use epydoc in pyparsing), and use the markup syntax recognized by that tool. Run that tool often while you are doing your development, to identify holes in your documentation. In fact, you might even benefit from writing the docstrings for the members of a class before implementing the class.