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 a new user                                                           def add self

User · Answer

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

User · Answer

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

User · Answer

Use a docstring      A string literal that occurs as the first statement in a module  function  class  or method definition  Such a docstring becomes the   doc   special attribute of that object       All modules should normally have docstrings  and all functions and classes exported by a module should also have docstrings  Public methods  including the   init   constructor  should also have docstrings  A package may be documented in the module docstring of the   init   py file in the package directory       String literals occurring elsewhere in Python code may also act as documentation  They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes  i e  not assigned to   doc      but two types of extra docstrings may be extracted by software tools          String literals occurring immediately after a simple assignment at the top level of a module  class  or   init   method are called  attribute docstrings     String literals occurring immediately after another docstring are called  additional docstrings           Please see PEP 258    Docutils Design Specification   2    for a detailed description of attribute and additional docstrings

User · Answer

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

User · Answer

Use docstrings  This is the built-in suggested convention in PyCharm for describing function using docstring comments  def test function p1  p2  p3        quot  quot  quot      test function does blah blah blah        param p1  describe about parameter p1      param p2  describe about parameter p2      param p3  describe about parameter p3      return  describe what it returns      quot  quot  quot       pass

User · Answer

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

User · Answer

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  You can also use any valid Python string  It doesn t need to be multiline and double quotes can be replaced by single quotes    See  PEP 257

User · Answer

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

User · Answer

You can use three quotes to do it   You can use single quotes   def myfunction para1 para2           The stuff inside the function         Or double quotes   def myfunction para1 para2           The stuff inside the function

User · Answer

While I agree that this should not be a comment  but a docstring as most  all   answers suggest  I want to add numpydoc  a docstring style guide    If you do it like this  you can  1  automatically generate documentation and  2  people recognize this and have an easier time to read your code

[python] What is the proper way to comment functions in Python?

Examples related to python