Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / Python

docstring — cadena de documentación

Un docstring es un literal de cadena ordinario (no una f-string ni una t-string) que se utiliza como primera instrucción de un módulo, una clase o una función. Documenta la finalidad del objeto y está disponible mediante __doc__; no es un comentario que empiece por #.

Versión: Python 3.14; repository image, production runtime not attested

Sintaxis

def function_name():
    """Describe the function's purpose."""
    pass

Un docstring es un literal de cadena ordinario (no una f-string ni una t-string) que se sitúa como primera instrucción de un módulo, una clase o una función, incluidos los métodos. Python lo expone como atributo __doc__ del objeto. Las herramientas pueden utilizar este contenido para mostrar documentación.

Ni un literal de cadena formateada (f-string) ni un literal de cadena de plantilla (t-string) crea un docstring, aunque el literal no contenga campos de sustitución y sea la primera instrucción. Si la primera instrucción de una función es f"""Description.""", su atributo __doc__ vale None.

Un comentario que empieza por # no crea un docstring. Un literal de cadena independiente situado después de otra instrucción tampoco se convierte en el docstring principal del objeto. Las comillas triples """...""" son prácticas, sobre todo para varias líneas, pero no bastan por sí solas: importan tanto el tipo de literal como su posición.

Por convención, la primera línea debe describir brevemente la finalidad del objeto, empezar con mayúscula y terminar con un punto. Separa la descripción adicional con una línea en blanco; explica los argumentos, los resultados y los efectos secundarios cuando sea necesario. Son recomendaciones sobre el contenido, no requisitos de sintaxis.

En el ejemplo, square.__doc__ permite acceder a la descripción, mientras que square(5) calcula el resultado independientemente de la documentación. La opción -OO elimina los docstrings, por lo que el código de una aplicación no debería depender de que estén presentes.

Ejemplos

def square(number):
    """Return the square of number."""
    return number * number

print(square.__doc__)
print(square(5))

Resultado

Return the square of number.
25

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes