Cuando se trata de escribir código limpio y bien documentado, los desarrolladores de Python tienen un arma secreta a su disposición: las cadenas de documentos. Las cadenas de documentos, abreviatura de cadenas de documentación, son vitales para transmitir el propósito y la funcionalidad de Pitón funciones, módulos y clases.
¿Cuáles son las cadenas de documentación en Python?
Pitón Las cadenas de documentación (o cadenas de documentos) proporcionan una manera conveniente de asociar documentación con Módulos de Python , funciones, clases y métodos. Se especifica en el código fuente que se utiliza, como un comentario, para documentar un segmento específico de código. A diferencia de los comentarios del código fuente convencional, la cadena de documentación debe describir qué hace la función, no cómo.
- Declaración de cadenas de documentos : Las cadenas de documentación se declaran utilizando 'comillas simples triples' o comillas dobles triples justo debajo de la declaración de clase, método o función. Todas las funciones deben tener una cadena de documentación.
- Accediendo a cadenas de documentos : Se puede acceder a las cadenas de documentación utilizando el método __doc__ del objeto o utilizando la función de ayuda. Los siguientes ejemplos demuestran cómo declarar y acceder a una cadena de documentos.
¿Cómo debería verse una cadena de documentación?
- La línea de la cadena de documentos debe comenzar con una letra mayúscula y terminar con un punto.
- La primera línea debe ser una breve descripción.
- Si hay más líneas en la cadena de documentación, la segunda línea debe estar en blanco, separando visualmente el resumen del resto de la descripción.
- Las siguientes líneas deben ser uno o más párrafos que describan las convenciones de llamada, los efectos secundarios, etc. del objeto.
Cadenas de documentos en Python
A continuación se detallan los temas que cubriremos en este artículo:
- Cadenas con comillas triples
- Cadenas de documentos de estilo Google
- Cadenas de documentos de estilo Numpydoc
- Cadenas de documentos de una línea
- Cadenas de documentos de varias líneas
- Sangría en cadenas de documentos
- Cadenas de documentación en clases
- Diferencia entre comentarios de Python y cadenas de documentos
Cadenas con comillas triples
Este es el formato de cadena de documentación más común en Python. Implica el uso de comillas triples (simples o dobles) para encerrar el texto de la documentación. Las cadenas entre comillas triples pueden abarcar varias líneas y, a menudo, se colocan inmediatamente debajo de la definición de función, clase o módulo.
Ejemplo 1: Usando comillas simples triples
Python3
def> my_function():> >'''Demonstrates triple double quotes> >docstrings and does nothing really.'''> > >return> None> print>(>'Using __doc__:'>)> print>(my_function.__doc__)> print>(>'Using help:'>)> help>(my_function)> |
>
>
Producción:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.>
Ejemplo 2: Usando comillas triples-dobles
Python3
def> my_function():> >' '> 'Demonstrates triple double quotes docstrings and does nothing really'> ' '> > >return> None> print>(>'Using __doc__:'>)> print>(my_function.__doc__)> print>(>'Using help:'>)> help>(my_function)> |
>
>
Producción:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.>
Cadenas de documentos de estilo Google
Las cadenas de documentación de estilo de Google siguen un formato específico y están inspiradas en la guía de estilo de documentación de Google. Proporcionan una forma estructurada de documentar el código Python, incluidos parámetros, valores de retorno y descripciones.
Python3
def> multiply_numbers(a, b):> >'''> >Multiplies two numbers and returns the result.> >Args:> >a (int): The first number.> >b (int): The second number.> >Returns:> >int: The product of a and b.> >'''> >return> a>*> b> print>(multiply_numbers(>3>,>5>))> |
>
>Producción
java si declaración
15>
Cadenas de documentos de estilo Numpydoc
Las cadenas de documentación de estilo Numpydoc se utilizan ampliamente en la comunidad científica y de análisis de datos, particularmente para documentar funciones y clases relacionadas con cálculos numéricos y manipulación de datos. Es una extensión de las cadenas de documentos al estilo de Google, con algunas convenciones adicionales para documentar parámetros y valores de retorno.
Python3
def> divide_numbers(a, b):> >'''> >Divide two numbers.> >Parameters> >----------> >a : float> >The dividend.> >b : float> >The divisor.> >Returns> >-------> >float> >The quotient of the division.> >'''> >if> b>=>=> 0>:> >raise> ValueError(>'Division by zero is not allowed.'>)> >return> a>/> b> print>(divide_numbers(>3>,>6>))> |
>
>Producción
0.5>
Cadenas de documentos de una línea
Como sugiere el nombre, las cadenas de documentación de una línea caben en una sola línea. Se utilizan en casos obvios. Las cotizaciones de cierre están en la misma línea que las cotizaciones de apertura. Esto se ve mejor para frases ingeniosas. Por ejemplo:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Producción:
Returns arg1 raised to power arg2.>
Cadenas de documentos de varias líneas
Las cadenas de documentación de varias líneas constan de una línea de resumen similar a una cadena de documentación de una línea, seguida de una línea en blanco y de una descripción más elaborada. La línea de resumen puede estar en la misma línea que las comillas iniciales o en la línea siguiente. El siguiente ejemplo muestra una cadena de documentación de varias líneas.
Python3
def> add_numbers(a, b):> >'''> >This function takes two numbers as input and returns their sum.> >Parameters:> >a (int): The first number.> >b (int): The second number.> >Returns:> >int: The sum of a and b.> >'''> >return> a>+> b> print>(add_numbers(>3>,>5>))> |
>
>
Producción:
8>
Sangría en cadenas de documentos
Toda la cadena de documentación tiene la misma sangría que las comillas en la primera línea. Las herramientas de procesamiento de cadenas de documentos eliminarán una cantidad uniforme de sangría de la segunda y siguientes líneas de la cadena de documentos, igual a la sangría mínima de todas las líneas que no estén en blanco después de la primera línea. Cualquier sangría en la primera línea de la cadena de documentación (es decir, hasta la primera línea nueva) es insignificante y se elimina. Se conserva la sangría relativa de las líneas posteriores en la cadena de documentación.
Python3
class> Employee:> >'''> >A class representing an employee.> >Attributes:> >name (str): The name of the employee.> >age (int): The age of the employee.> >department (str): The department the employee works in.> >salary (float): The salary of the employee.> >'''> >def> __init__(>self>, name, age, department, salary):> >'''> >Initializes an Employee object.> >Parameters:> >name (str): The name of the employee.> >age (int): The age of the employee.> >department (str): The department the employee works in.> >salary (float): The salary of the employee.> >'''> >self>.name>=> name> >self>.age>=> age> >self>.department>=> department> >self>.salary>=> salary> >def> promote(>self>, raise_amount):> >'''> >Promotes the employee and increases their salary.> >Parameters:> >raise_amount (float): The raise amount to increase the salary.> >Returns:> >str: A message indicating the promotion and new salary.> >'''> >self>.salary>+>=> raise_amount> >return> f>'{self.name} has been promoted! New salary: ${self.salary:.2f}'> >def> retire(>self>):> >'''> >Marks the employee as retired.> >Returns:> >str: A message indicating the retirement status.> >'''> ># Some implementation for retiring an employee> >return> f>'{self.name} has retired. Thank you for your service!'> # Access the Class docstring using help()> help>(Employee)> |
>
>
Producción:
class Employee | A class representing an employee. | | Attributes: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | Methods defined here: | | __init__(self, name, age, department, salary) | Initializes an Employee object. | | Parameters: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | promote(self, raise_amount) | Promotes the employee and increases their salary. | | Parameters: | raise_amount (float): The raise amount to increase the salary. | | Returns: | str: A message indicating the promotion and new salary. | | retire(self) | Marks the employee as retired. | | Returns: | str: A message indicating the retirement status.>
Cadenas de documentación en clases
Tomemos un ejemplo para mostrar cómo escribir cadenas de documentación para una clase y el método ' ayuda' se utiliza para acceder a la cadena de documentación.
Python3
class> ComplexNumber:> >'''> >This is a class for mathematical operations on complex numbers.> >Attributes:> >real (int): The real part of the complex number.> >imag (int): The imaginary part of the complex number.> >'''> >def> __init__(>self>, real, imag):> >'''> >The constructor for ComplexNumber class.> >Parameters:> >real (int): The real part of the complex number.> >imag (int): The imaginary part of the complex number.> >'''> >self>.real>=> real> >self>.imag>=> imag> >def> add(>self>, num):> >'''> >The function to add two Complex Numbers.> >Parameters:> >num (ComplexNumber): The complex number to be added.> >Returns:> >ComplexNumber: A complex number which contains the sum.> >'''> >re>=> self>.real>+> num.real> >im>=> self>.imag>+> num.imag> >return> ComplexNumber(re, im)> # Access the Class docstring using help()> help>(ComplexNumber)> # Access the method docstring using help()> help>(ComplexNumber.add)> |
>
>
Producción:
Help on class ComplexNumber in module __main__: class ComplexNumber(builtins.objects) | This is a class for mathematical operations on complex numbers. | | Attributes: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | Methods defined here: | | __init__(self, real, imag) | The constructor for ComplexNumber class. | | Parameters: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | add(self, num) | The function to add two Complex Numbers. | | Parameters: | num (ComplexNumber): The complex number to be added. | | Returns: | ComplexNumber: A complex number which contains the sum. Help on method add in module __main__: add(self, num) unbound __main__.ComplexNumber method The function to add two Complex Numbers. Parameters: num (ComplexNumber): The complex number to be added. Returns: ComplexNumber: A complex number which contains the sum.>
Diferencia entre comentarios, cadenas y cadenas de documentos de Python
Cadena: en Python, una cadena es una secuencia de caracteres encerrados entre comillas simples (' ') o comillas dobles (). Las cadenas se utilizan para representar datos de texto y pueden contener letras, números, símbolos y espacios en blanco. Son uno de los tipos de datos fundamentales en Python y pueden manipularse utilizando varios métodos de cadena.
Todos debéis tener una idea sobre las cadenas de documentación de Python, pero ¿alguna vez os habéis preguntado cuál es la diferencia entre los comentarios de Python y las cadenas de documentación? Echemos un vistazo a ellos.
Son información útil que proporcionan los desarrolladores para que el lector comprenda el código fuente. Explica la lógica o una parte de ella utilizada en el código. Está escrito usando
#>
símbolos.
Ejemplo:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Producción:
GFG>
Mientras que Python Docstrings, como se mencionó anteriormente, proporciona una forma conveniente de asociar documentación con módulos, funciones, clases y métodos de Python.