What is the proper way to comment functions in Python?

Question

Is there a generally accepted way to comment functions in Python? Is the following acceptable?

#########################################################
# Create         


        

Answer 1

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

• 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, and Javadoc in Java