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

6 minutos de lectura

avatar de usuario
entrampar

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

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

avatar de usuario
Chinmay Kanchi

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 terminarlo. También puede usar cualquier cadena de Python válida. No es necesario que sea multilínea y las comillas dobles se pueden reemplazar por comillas simples.

Ver: PEP 257

  • Tenga en cuenta que no tiene que estar entre comillas triples; cualquier literal de cadena funcionará. Pero puede poner más información en una cadena de varias líneas.

    – Ignacio Vázquez-Abrams

    1 de marzo de 2010 a las 16:25

  • Aunque la convención dicta que debe citarse tres veces. Nunca he visto una cadena de documentación que no lo fuera.

    – Chinmay Kanchi

    1 de marzo de 2010 a las 16:27

  • Lo que no quiere decir que no esté de acuerdo. Deben estar citados tres veces, pero verás algunos en la naturaleza que no lo están.

    – jcdyer

    1 de marzo de 2010 a las 18:22

  • También puede usar tres comillas simples (en lugar de tres comillas dobles) para abrir y cerrar la cadena de documentación.

    –Craig McQueen

    1 de marzo de 2010 a las 23:39

  • ¿No deberías sangrar el comentario también?

    – jockey

    19 de febrero de 2014 a las 11:01

avatar de usuario
Shwetabh Shekhar

Usar cadenas de documentación.

Esta es la convención sugerida integrada en PyCharm para describir la función usando comentarios de cadena de documentación:

def test_function(p1, p2, p3):
    """
    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
    """ 
    pass

  • ¿No debería estar sangrado (después de la línea con def)? (No es una pregunta retórica.)

    -Peter Mortensen

    3 de febrero de 2020 a las 16:53

  • Me gusta este estilo, pero cuando paso el mouse sobre mi función, todo lo que obtengo son argumentos -> no muestra ninguna información descriptiva, ¿alguna idea?

    – Ricardo Sánchez

    15 de enero de 2021 a las 23:47

  • @RicardoSanchez ¿En qué IDE obtienes este estilo? El código VS generalmente muestra todo después de pasar el mouse y Pycharm no muestra nada si pasa el mouse.

    – Shwetabh Shekhar

    25 de marzo de 2021 a las 7:15

  • @ShwetabhShekhar Acabo de verificar nuevamente y funciona en VSCode, debe haber sido después de una actualización, gracias.

    – Ricardo Sánchez

    25 de marzo de 2021 a las 9:12

  • IntelliJ IDEA da un “Signo de puntuación flojo”. advertencia

    – Filippo Vitale

    21 de marzo a las 14:57

Use una cadena de documentación, como ya han escrito otros.

Incluso puede ir un paso más allá y agregar un doctest a su cadena de documentos, lo que hace que las pruebas automatizadas de sus funciones sean muy sencillas.

  • Esta respuesta es bastante débil sin seguir hasta la página vinculada.

    – xaxxon

    10 abr 2019 a las 21:49

avatar de usuario
Deniz Dogan

Utilizar una cadena de documentación:

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 docstring se convierte en el __doc__ atributo especial de ese objeto.

Todos los módulos normalmente deberían tener cadenas de documentación, y todas las funciones y clases exportadas por un módulo también deberían tener cadenas de documentación. Métodos públicos (incluido el __init__ constructor) también debe tener cadenas de documentación. Un paquete puede estar documentado en la cadena de documentación del módulo del __init__.py archivo 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. No son reconocidos por el compilador de código de bytes de Python y no son accesibles como atributos de objetos de tiempo de ejecución (es decir, no están asignados a __doc__ ), pero las herramientas de software pueden extraer dos tipos de cadenas de documentos adicionales:

  1. Literales de cadena que ocurren inmediatamente después de una asignación simple en el nivel superior de un módulo, clase o __init__ se denominan “docstrings de atributo”.
  2. Los literales de cadena que aparecen inmediatamente después de otra cadena de documentación se denominan “cadenas de documentación adicionales”.

Por favor mira PEP 258 “Especificación de diseño de Docutils” [2] para obtener una descripción detallada del atributo y cadenas de documentación adicionales…

avatar de usuario
Dancrumb

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

  • Los comentarios de función deben describir el intención de una función, no la implementación
  • Describa cualquier suposición que haga su función con respecto al estado del sistema. Si usa alguna variable global (tsk, tsk), enumérelas.
  • Cuidado con el exceso arte ASCII. Tener largas cadenas de hashes puede parecer que hace que los comentarios sean más fáciles de leer, pero puede ser molesto lidiar con ellos cuando los comentarios cambian.
  • Aproveche las características del lenguaje que proporcionan ‘documentación automática’, es decir, cadenas de documentos en Python, POD en Perl y Javadoc en Java.

  • no hay nada subjetivo en esto, Python es muy claro sobre el uso de comentarios de Docstring.

    usuario177800

    1 de marzo de 2010 a las 16:37

  • @fuzzy lollipop, agradezco el comentario, pero notarás que mi último punto hace ese punto exacto. Quizás la pregunta del OP es solo sobre la mecánica de comentar en Python, pero no creo que mi respuesta justifique una votación negativa.

    – Dancrumb

    1 de marzo de 2010 a las 16:56

avatar de usuario
Pedro Mortensen

Leer sobre el uso cadenas de documentación en su código Python.

Según Python convenciones de cadenas de documentación:

La cadena de documentación para una función o método debe resumir su comportamiento y documentar sus argumentos, valores devueltos, efectos secundarios, excepciones planteadas y restricciones sobre cuándo se puede llamar (todo si corresponde). Deben indicarse los argumentos opcionales. Debe documentarse si los argumentos de palabras clave son parte de la interfaz.

No habrá una regla de oro, sino proporcionar comentarios que signifiquen algo para los otros desarrolladores de su equipo (si tiene uno) o incluso para usted mismo cuando vuelva a hacerlo dentro de seis meses.

  • no hay nada subjetivo en esto, Python es muy claro sobre el uso de comentarios de Docstring.

    usuario177800

    1 de marzo de 2010 a las 16:37

  • @fuzzy lollipop, agradezco el comentario, pero notarás que mi último punto hace ese punto exacto. Quizás la pregunta del OP es solo sobre la mecánica de comentar en Python, pero no creo que mi respuesta justifique una votación negativa.

    – Dancrumb

    1 de marzo de 2010 a las 16:56

avatar de usuario
Pedro Mortensen

Yo optaría por una práctica de documentación que se integre con una herramienta de documentación como Esfinge.

El primer paso es utilizar un docstring:

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

¿Ha sido útil esta solución?

Esta web utiliza cookies propias y de terceros para su correcto funcionamiento y para fines analíticos y para mostrarte publicidad relacionada con sus preferencias en base a un perfil elaborado a partir de tus hábitos de navegación. Al hacer clic en el botón Aceptar, acepta el uso de estas tecnologías y el procesamiento de tus datos para estos propósitos. Configurar y más información
Privacidad