Python Language
Comentarios y Documentación

Sintaxis

• # Este es un comentario de una sola línea.
• imprimir ("") # Este es un comentario en línea
• ""
  Esto es
  un comentario multilínea
  ""

Observaciones

Comentarios de línea única, en línea y multilínea.

Los comentarios se utilizan para explicar el código cuando el código básico en sí no está claro.

Python ignora los comentarios, por lo que no ejecutará el código allí, ni generará errores de sintaxis para las oraciones simples en inglés.

Los comentarios de una sola línea comienzan con el carácter de hash ( # ) y terminan al final de la línea.

• Comentario de una sola línea:

# This is a single line comment in Python

• Comentario en línea:

print("Hello World")  # This line prints "Hello World"

• Los comentarios que abarcan varias líneas tienen """ o ''' en cualquiera de los extremos. Es lo mismo que una cadena multilínea, pero se pueden usar como comentarios:

"""
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
"""

Accediendo programáticamente a las cadenas de documentación

Las cadenas de documentos son, a diferencia de los comentarios regulares, almacenados como un atributo de la función que documentan, lo que significa que puede acceder a ellos mediante programación.

Una función de ejemplo

def func():
    """This is a function that does nothing at all"""
    return

Se puede acceder a la __doc__ utilizando el atributo __doc__ :

print(func.__doc__)

Esta es una función que no hace nada en absoluto.

help(func)

Ayuda en la función de func en el módulo __main__ :

func()

Esta es una función que no hace nada en absoluto.

Otra función de ejemplo

function.__doc__ es solo la cadena de documentos real como una cadena, mientras que la función de help proporciona información general sobre una función, incluida la cadena de documentos. Aquí hay un ejemplo más útil:

def greet(name, greeting="Hello"):
    """Print a greeting to the user `name`

    Optional parameter `greeting` can change what they're greeted with."""
    
    print("{} {}".format(greeting, name))

help(greet)

Ayuda en función greet en el módulo __main__ :

greet(name, greeting='Hello')

Imprime un saludo al name usuario
El parámetro de greeting opcional puede cambiar lo que se saluda con.

Ventajas de docstrings sobre comentarios regulares

El solo hecho de no poner una cadena de documentos o un comentario regular en una función hace que sea mucho menos útil.

def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.
    
    print("{} {}".format(greeting, name))

print(greet.__doc__)

Ninguna

help(greet)

Ayuda en función saludar en módulo principal :

greet(name, greeting='Hello')

Escribir documentación utilizando cadenas de documentación.

Una cadena de documentación es un comentario de varias líneas que se utiliza para documentar módulos, clases, funciones y métodos. Tiene que ser la primera declaración del componente que describe.

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)

class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

Se puede acceder al valor de la cadena de documentos dentro del programa y, por ejemplo, el comando de help utiliza.

Convenciones de sintaxis

PEP 257

PEP 257 define un estándar de sintaxis para comentarios de cadena de documentación. Básicamente permite dos tipos:

• Docstrings de una línea:

Según PEP 257, deben usarse con funciones cortas y simples. Todo se coloca en una línea, por ejemplo:

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

La cadena de documentos debe terminar con un punto, el verbo debe estar en la forma imperativa.

• Docstrings multilínea:

La cadena de documentos multilínea se debe utilizar para funciones, módulos o clases más largas y complejas.

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

Comienzan con un breve resumen (equivalente al contenido de una cadena de documentación de una línea) que puede estar en la misma línea que las comillas o en la siguiente línea, dan detalles adicionales y enumeran parámetros y valores de retorno.

La nota PEP 257 define qué información se debe dar dentro de una cadena de documentación, no define en qué formato se debe dar. Esta fue la razón para que otras partes y herramientas de análisis de documentación especifiquen sus propios estándares para la documentación, algunos de los cuales se enumeran a continuación y en esta pregunta .

Esfinge

Sphinx es una herramienta para generar documentación basada en HTML para proyectos de Python basados ​​en cadenas de documentación. Su lenguaje de marcado utilizado es reStructuredText . Definen sus propios estándares para la documentación, pythonhosted.org alberga una muy buena descripción de ellos . El formato Sphinx es, por ejemplo, utilizado por el IDE de pyCharm .

Una función se documentaría así utilizando el formato Sphinx / reStructuredText:

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Guía de estilo de Google Python

Google ha publicado la Guía de estilo de Google Python que define las convenciones de codificación para Python, incluidos los comentarios de la documentación. En comparación con Sphinx / reST, muchas personas dicen que la documentación de acuerdo con las directrices de Google es mejor legible para los humanos.

La página pythonhosted.org mencionada anteriormente también proporciona algunos ejemplos de buena documentación de acuerdo con la Guía de estilo de Google.

Al usar el complemento de Napoleón , Sphinx también puede analizar la documentación en el formato compatible con la Guía de estilo de Google.

Una función se documentaría así utilizando el formato de la Guía de estilo de Google:

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4