Python Docstring

La documentación es esencial para cualquier programación para comprender el código fácilmente. Se utiliza para explicar el propósito de usar cualquier declaración, función o clase o módulo en el programa. Ayuda al codificador principal a recordar la función de cualquier código después de mucho tiempo, y también ayuda a otros codificadores que desean trabajar en el mismo proyecto. El codificador utiliza una sola línea de comentario para explicar la parte particular de la función del código en breve. La cadena de documento de Python o el documento se utiliza para explicar la función de un segmento particular del código en detalle. La línea de documentos debe comenzar con la letra mayúscula y terminar con un período. La primera línea del documento contiene una breve descripción de la documentación en general. La segunda línea de la documentación debe estar en blanco para el gran documento de múltiples líneas. Citas triple individuales ('”) o Cotizaciones dobles triple ("" ") se usan para definir la documentación en Python. Se puede acceder al contenido de documentos utilizando El documento__ atributo del objeto y usar el ayuda() método. La forma de declarar y acceder a Docstring en Python se ha mostrado en este tutorial.

Ejemplo-1: acceder a la documentación de una función utilizando __doc__ atributo

La forma de declarar y acceder a la documentación de una función personalizada se ha mostrado en el siguiente script. El siguiente script calcula la x^norte donde x y n serán tomados del usuario. Fuerza () la función ha definido en el script para hacer la tarea. Aquí, el documento se ha definido para esta función. __doc__ El atributo se ha utilizado en el script para imprimir el documento con la salida.

Power de def (x, n):
"Calcule x a la potencia n
Lea los valores de X y N de los argumentos de la función
y calcule y devuelva el valor de x a la potencia n."
regresar x ** n
# Tomar el valor de x
x = int (input ('Ingrese el valor de x:'))
# Tomar el valor de n
n = int (input ('Ingrese el valor de n:'))
# Imprima el valor de retorno de la funntion
Imprimir ("El %D a la potencia %d = %d" %(x, n, potencia (x, n))))
# Imprima el valor de documentos
Imprimir ("El contenido del documento: \ n" + potencia.__doc__)

Producción:

La siguiente salida aparecerá después de ejecutar el script anterior.

Ejemplo-2: acceder a la documentación de clase y método utilizando ayuda() método

La forma de declarar y acceder a la documentación del documento y los métodos de esa clase se han mostrado en el siguiente script. La función principal del script es ordenar una lista numérica e revertir los datos de la lista. Se ha declarado una lista numérica de 8 elementos en la clase, y la documentación se ha definido al comienzo de la clase utilizando citas triples individuales. El método sort_list () se ha definido en la clase para imprimir los datos ordenados de la lista, y el documento ha definido esto Para este método. reverse_list () El método se define para imprimir los datos invertidos de la lista, y el documento también se ha definido para este método. ayuda() El método ha llamado tres veces al final del script para imprimir el documento de la list_perations clase, Lista Ordenada() método y el reverse_list () método.

Class List_Operations:

Class List_Operations:
"
Ordenar y revertir los datos de la lista
La clase contiene dos métodos,
El método sort_list () ordenará e imprimirá la lista,
El método sort_reverse () revertirá e imprimirá la lista.
"
# Definir una lista de datos numéricos
listData = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list (self):
"
Imprima los valores de la lista después de clasificar
La función tomará un objeto de lista de datos numéricos del argumento,
Ordene los valores de la lista utilizando el método sort ()
e imprima los valores de la lista ordenada.
"
# Ordenar la lista
ser.datos de listas.clasificar()
# Imprima la lista ordenada usando bucle
imprimir ("Los valores de la lista ordenada: \ n")
Para el valor en uno mismo.ListData:
imprimir (valor, "", end = ")
Def reverse_list (self):
"
Imprima los valores de la lista después de revertir
La función tomará un objeto de lista de datos numéricos del argumento,
Revertir los valores de la lista usando el método reverse ()
e imprima los valores de la lista invertida.
"
# Invertir la lista
ser.datos de listas.contrarrestar()
# Imprima la lista invertida usando el bucle
imprimir ("Los valores de la lista ordenada: \ n")
Para el valor en uno mismo.ListData:
imprimir (valor, "", end = ")
# Imprima el valor de documentos de la clase
Ayuda (List_Operations)
# Crear objeto de la clase
obj = list_operations ()
# Imprima el valor de documentos del método particular
Ayuda (OBJ.Lista Ordenada)
# Llame al método para imprimir la lista ordenada
obj.Lista Ordenada()

Producción:

La siguiente salida aparecerá después de ejecutar el script. Todo el documento del script se ha imprimido para el primero ayuda() función. El documento de la Lista Ordenada() el método se ha imprimido para el segundo ayuda() función.

Ejemplo-3: Acceso a la documentación del módulo Python incorporado

En los ejemplos anteriores, el documento se ha utilizado en clase y función definidas por el usuario. Cada módulo y clase de Python incorporados tiene su documento que explica el propósito de usar ese módulo o función en particular. El codificador del módulo o función define el documento para que el código sea comprensible para los usuarios. El siguiente script imprimirá el documento predefinido del módulo DateTime utilizando el ayuda() función.

# Importar el módulo de fecha y hora
Importar DateTetime
# Muestra el documento de DateTime
Ayuda (DateTime)

Producción:

La siguiente salida aparecerá después de ejecutar el script. El documento del módulo DateTime muestra la documentación detallada del mismo para ayudar a los demás a conocer las funciones de las clases y métodos definidos en este módulo correctamente.

Conclusión:

La documentación adecuada es esencial cuando se implementa cualquier módulo o función para el propósito específico para ayudar al otro codificador a usar el módulo en su código para realizar la tarea particular. Si la documentación no se define correctamente para el módulo o la función, los otros usuarios enfrentarán problemas a usarla. Por lo tanto, cada codificador debe usar el documento del documento para proporcionar información detallada para que los demás comprendan el código.