¿Cuál es la forma correcta de comentar funciones en Python?

¿Hay una forma generalmente aceptada de comentar funciones en Python? ¿Es aceptable lo siguiente?

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

La forma correcta de hacerlo es proporcionar una cadena de documentación. De esa manera, help(add)también escupirá tu comentario.

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

Son tres comillas dobles para abrir el comentario y otras tres comillas dobles para finalizarlo. También puede usar cualquier cadena Python válida. No necesita ser multilínea y las comillas dobles se pueden reemplazar por comillas simples.

Ver: PEP 257

Use una cadena de documentos, como otros ya han escrito.

Incluso puede ir un paso más allá y agregar un doctest a su docstring, haciendo que la prueba automatizada de sus funciones sea muy fácil.

Use una cadena de documentos :

Un literal de cadena que aparece como la primera instrucción en una definición de módulo, función, clase o método. Tal cadena de documentación se convierte en el __doc__atributo especial de ese objeto.

Todos los módulos normalmente deben tener cadenas de documentos, y todas las funciones y clases exportadas por un módulo también deben tener cadenas de documentos. Los métodos públicos (incluido el __init__constructor) también deben tener cadenas de documentos. Un paquete puede documentarse en la cadena de documentación del módulo del __init__.pyarchivo en el directorio del paquete.

Los literales de cadena que aparecen en otras partes del código de Python también pueden actuar como documentación. El compilador __doc__de código de bytes de Python no los reconoce y no son accesibles como atributos de objeto de tiempo de ejecución (es decir, no asignados a ellos ), pero las herramientas de software pueden extraer dos tipos de cadenas de documentos adicionales:

1. Los literales de cadena que ocurren inmediatamente después de una asignación simple en el nivel superior de un módulo, clase o __init__método se denominan "cadenas de documentación de atributos".
2. Los literales de cadena que aparecen inmediatamente después de otra cadena de documentación se denominan "cadenas de documentación adicionales".

Consulte PEP 258 , "Especificación de diseño de Docutils" [2] , para obtener una descripción detallada del atributo y cadenas de documentos adicionales ...

Los principios de los buenos comentarios son bastante subjetivos, pero aquí hay algunas pautas:

• Los comentarios de funciones deben describir la intención de una función, no la implementación
• Resuma cualquier suposición que haga su función con respecto al estado del sistema. Si usa alguna variable global (tsk, tsk), enumere esas.
• Cuidado con el excesivo art . ASCII . Tener cadenas largas de hash puede hacer que los comentarios sean más fáciles de leer, pero puede ser molesto tratarlos cuando cambian los comentarios
• Aproveche las funciones de lenguaje que proporcionan 'documentación automática', es decir, cadenas de documentos en Python, POD en Perl y Javadoc en Java

Lea sobre el uso de docstrings en su código Python.

Según las convenciones de docstring de Python :

La cadena de documentos para una función o método debe resumir su comportamiento y documentar sus argumentos, valores de retorno, efectos secundarios, excepciones generadas y restricciones sobre cuándo se puede invocar (todo si corresponde). Se deben indicar argumentos opcionales. Debe documentarse si los argumentos de palabras clave son parte de la interfaz.

No habrá una regla de oro, sino más bien proporcione comentarios que signifiquen algo para los otros desarrolladores de su equipo (si tiene uno) o incluso para usted cuando vuelva a hacerlo seis meses después.

Iría por una práctica de documentación que se integra con una herramienta de documentación como Sphinx .

El primer paso es usar un docstring:

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

Yo iría un paso más allá que simplemente decir "usar una cadena de documentación". Elija una herramienta de generación de documentación, como pydoc o epydoc (uso epydoc en pyparsing), y use la sintaxis de marcado reconocida por esa herramienta. Ejecute esa herramienta a menudo mientras realiza su desarrollo, para identificar agujeros en su documentación. De hecho, incluso podría beneficiarse de escribir las cadenas de documentos para los miembros de una clase antes de implementar la clase.

Use docstrings .

Esta es la convención sugerida incorporada en PyCharm para comentarios de descripción de funciones:

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

Si bien estoy de acuerdo en que esto no debería ser un comentario, sino una cadena de documentación como sugieren la mayoría (¿todas?), Quiero agregar numpydoc (una guía de estilo de documentación) .

Si lo hace así, puede (1) generar automáticamente documentación y (2) las personas lo reconocen y es más fácil leer su código.

Puedes usar tres comillas para hacerlo.

Puedes usar comillas simples:

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

O comillas dobles:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """