python - how - Docstrings vs Comentarios

python param doc

Question

Estoy un poco confundido sobre la diferencia entre docstrings y comentarios en python.

En mi clase, mi profesor introdujo algo conocido como una ''receta de diseño'', un conjunto de pasos que supuestamente nos ayudará a los estudiantes a trazar y organizar mejor nuestra codificación en Python. Por lo que entiendo, lo que sigue es un ejemplo de los pasos que seguimos, lo que se denomina receta de diseño (las cosas en las citas):

def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark):

    '''''' (float, float, float, float, float) -> float

    Takes your marks on a0_mark, a1_mark, a2_mark, ex_mark and midterm_mark, 
    calculates their respective weight contributions and sums these 
    contributions to deliver your overall term mark out of a maximum of 55 (This
    is because the exam mark is not taken account of in this function)

    >>>term_work_mark(5, 5, 5, 5, 5)
    11.8
    >>>term_work_mark(0, 0, 0, 0, 0)
    0.0
    ''''''

    a0_component = contribution(a0_mark, a0_max_mark, a0_weight)
    a1_component = contribution(a1_mark, a1_max_mark, a1_weight)
    a2_component = contribution(a2_mark, a2_max_mark, a2_weight)
    ex_component = contribution(ex_mark, exercises_max_mark,exercises_weight)
    mid_component = contribution(midterm_mark, midterm_max_mark, midterm_weight)
    return (a0_component + a1_component + a2_component + ex_component + 
            mid_component)

Por lo que entiendo, esto es básicamente una cadena de documentación, y en nuestra versión de una cadena de documentos debe incluir tres cosas: una descripción, ejemplos de lo que debería hacer su función si la ingresa en el shell de python, y un ''contrato de tipo'', una sección que muestra los tipos que ingresa y los tipos que devolverá la función.

Ahora todo está bien y listo, pero nuestras asignaciones requieren que también tengamos comentarios que expliquen la naturaleza de nuestras funciones, usando el símbolo "#" del token.

Entonces, mi pregunta es, ¿no he explicado ya qué hará mi función en la sección de descripción de la cadena de documentación? ¿Cuál es el punto de agregar comentarios si esencialmente le digo al lector exactamente lo mismo?

Answer 1

Citando desde esta página http://www.pythonforbeginners.com/basics/python-docstrings/

Las cadenas de documentación de Python (o cadenas de documentación) proporcionan una forma conveniente de asociar la documentación con los módulos, funciones, clases y métodos de Python.

La documentación de un objeto se define al incluir una cadena constante como la primera declaración en la definición del objeto.

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 de código fuente convencionales, la cadena de documentación debe describir lo que hace la función, no cómo.

Todas las funciones deben tener una cadena de documentación.

Esto permite que el programa inspeccione estos comentarios en tiempo de ejecución, por ejemplo, como un sistema de ayuda interactivo o como metadatos.

Se puede acceder a las cadenas de documentos mediante el atributo __ doc __ en los objetos.

1. Se puede acceder a las cadenas de documentos a través de un programa ( __doc__ ) donde no se puede acceder a los comentarios en línea.
2. Los sistemas de ayuda interactivos como en bpython e IPython pueden usar docstrings para mostrar el docsting durante el desarrollo. Para que no tengas que visitar el programa cada vez.

Answer 2

Creo que vale la pena mencionar lo que PEP8 dice, quiero decir, el concepto puro.

Cuerdas

Las convenciones para escribir cadenas de buena documentación (también conocidas como "cadenas de documentos") se inmortalizan en PEP 257.

Escribe cadenas de documentación para todos los módulos, funciones, clases y métodos públicos. Las cadenas de documentación no son necesarias para los métodos no públicos, pero debe tener un comentario que describa lo que hace el método. Este comentario debería aparecer después de la línea de definición.

PEP 257 describe buenas convenciones de docstring. Tenga en cuenta que lo más importante es que la "" "que termina una cadena de documentos multilínea debe estar sola en una línea, por ejemplo:

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

Para las cadenas de documentación de un forro, mantenga el cierre "" "en la misma línea.

Comentarios

Bloquear comentarios

Por lo general, se aplica a algunos (o todos) códigos que los siguen, y están sangrados al mismo nivel que ese código. Cada línea de un comentario de bloque comienza con un # y un solo espacio (a menos que sea un texto sangrado dentro del comentario).

Los párrafos dentro de un comentario de bloque están separados por una línea que contiene un solo #.

Comentarios en línea

Utilice los comentarios en línea con moderación.

Un comentario en línea es un comentario en la misma línea que una declaración. Los comentarios en línea deben estar separados por al menos dos espacios de la declaración. Deben comenzar con un # y un solo espacio.

Los comentarios en línea son innecesarios y, de hecho, distraen si establecen lo obvio.

No hagas esto

x = x + 1 # Incremento x

Pero a veces, esto es útil:

x = x + 1 # Compensar por borde

Referencia

• https://www.python.org/dev/peps/pep-0008/#documentation-strings
• https://www.python.org/dev/peps/pep-0008/#inline-comments
• https://www.python.org/dev/peps/pep-0008/#block-comments
• https://www.python.org/dev/peps/pep-0257/

Answer 3

En primer lugar, para dar formato a sus publicaciones, puede usar las opciones de ayuda sobre el área de texto en que escribe su publicación.

Y sobre los comentarios y las cadenas de documentos, la cadena de documentos está ahí para explicar el uso general y la información básica de los métodos. Por otro lado, los comentarios están destinados a proporcionar información específica sobre bloques o líneas, #TODO se usa para recordarle lo que desea hacer en el futuro, la definición de variables, etc. Por cierto, en IDLE, la cadena de documentos se muestra como una sugerencia de herramienta cuando se desplaza sobre el nombre del método.

Answer 4

Parece que tu profesor es un fan de Cómo diseñar programas;)

Trataré esto como escribir para dos audiencias diferentes que no siempre se superpondrán.

Primero están las cadenas de documentación; Estos son para personas que van a utilizar su código sin necesidad de saber cómo funciona. Las cadenas de documentos se pueden convertir en documentación real. Considere la documentación oficial de Python: lo que está disponible en cada biblioteca y cómo usarlo, sin detalles de implementación (a menos que estén directamente relacionados con el uso)

En segundo lugar hay comentarios en el código; estos son para explicar lo que está sucediendo a las personas (generalmente a usted) que desean extender el código. Normalmente, estos no se convertirán en documentación, ya que se refieren realmente al código en sí y no al uso. Ahora hay casi tantas opiniones sobre lo que hace buenos comentarios (o falta de ellos) como programadores. Mis reglas de oro personales para agregar comentarios son para explicar:

• Partes del código que son necesariamente complejas. (La optimización viene a la mente)
• Soluciones para el código sobre el que no tiene control, que de otra manera pueden parecer ilógicos
• Admito que TODOs también, aunque trato de mantener eso al mínimo
• Donde he elegido un algoritmo más simple donde una opción de mejor rendimiento (pero más compleja) puede ir si el rendimiento en esa sección se vuelve crítico más adelante

Ya que estás codificando en un entorno académico, y parece que tu profesor va por algo detallado, yo diría que simplemente sigue adelante. Use los comentarios de código para explicar cómo está haciendo lo que dice que está haciendo en la receta de diseño.