Especificaciones del código

El docstring o la documentación está dividido en tres partes importantes que son las siguientes:

• Primero se da una descripción clara y concisa de la función y su funcionamiento

• En medio se agrega la descripción de los diferentes parámetros, su tipo, su nombre y que es lo que se espera de esos parámetros

• Por ultimo se agrega que es lo que devuelve nuestra función

Les comparto una publicación excelente sobre buenas practicas con Python.
++Thomas Cokelaer - Ejemplo sobre cómo documentar sus cadenas de documentos en Python
++https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html

Les dejo algunas buenas prácticas que encontré

1. Recordar que en Python se maneja la indentación para delimitar bloques de instrucciones.
2. Escribir los programas los más simple posible.
3. Comentar los programas, explicando el propósito, funcionamiento completo y el resultado
   esperado.
4. Al inicio de cada función, agregar brevemente un comentario que explique el comportamiento
   general de la función.
5. Definir el nombre de funciones, variables y constantes que mejor representen el contenido que
   almacenarán.
6. No usar variables cuyo nombre carezca de significado descriptivo. Con un código legible y
   nombres significativos, el código se va auto documentado.
7. Declarar variables en líneas separadas, posibilitando agregar una descripción de cada variable
   mediante comentarios.
8. Definir el nombre de funciones, módulos y clases que mejor representen las acciones que
   realizan.
9. Definir el tamaño de las sangrías para que sean regulares (consistentes) y no varíen a lo largo
   del código, es decir, si el primer bloque ocupa como indentación una tabulación, el resto de
   bloques deben ser indentados con una tabulación adicional por cada nivel, con eso se facilita la
   lectura en cualquier editor de código.
   Ser consistente al momento de utilizar un estándar para nombres largos, por ejemplo para una
   variable que almacena cantidad de alumnos 'contador_alumnos’
   Comentar cuando sea justo y necesario, usar los comentarios dentro de las funciones para
   describir las variables (sólo cuando su utilidad sea potencialmente dudosa) y cuando existan
   bloques de código difíciles de entender a primera vista; el exceso de comentarios vuelve ilegible
   el código.
10. Definir variables locales al inicio de la implementación de cada función, como un bloque de
    código bien separado del bloque que contenga las instrucciones ejecutables, ésta separación
    puede consistir en una línea en blanco, o bien un comentario que denote la utilidad de cada
    bloque.
11. Evitar la incorporación de más de una instrucción por línea. Esto reduce notoriamente la
    legibilidad del código, ya que el programador habitualmente está acostumbrado a leer una
    instrucción por línea.
    Realizar la indentación necesaria, si una instrucción abarca más de una línea.

Documentacion:

1. La primera linea debe ser un resumen, importante que quepa en una sola linea y este separada del resto de docstrings por un espacion en blanco.

2. El resto de la cadena de documentación debe describir el comportamiento de la función.

3. Se recomienda dejar una línea en blanco antes de las triples comillas que cierran la cadena de documentación.

Fuente: http://edupython.blogspot.com/2013/12/documentando-programas-en-python.html

Y para saber más sobre la función “Help”, simplemente escribimos: help(help).
Resultado:

Especificaciones del codigo:

Tienen 3 partes fundamentales

1. Que hace la funcion
2. Que significan los parametros: Cual es el nombre del parametro y Cual es el tipo del parametro
3. Que regresa esta funcion

def suma(a, b):
	"""Suma dos valores a y b.

	param int a cualquier entero
	param int b cualquier entero
	returns la sumatoria de a y b
	"""

	total = a + b
	return total

Comparto un enlace donde se complementas algunas practicas adicionales para el lenguaje pyhton

http://research.iac.es/sieinvens//python-course/source/estilo.html

Aqui se puede ahondar algo en el tema:
https://edupython.blogspot.com/2013/12/documentando-programas-en-python.html

Me permito dejarles este link para profundizar más en los temas
https://www.w3schools.com/python/default.asp

En Html se usa <!-- COMENTARIO -->

Un docstring es la descripción de la interfaz de una función. La interfaz se compone de:

• Qué hace la función.
• Sus parámetros con su tipo y que se espera en ellos.
• Qué retorna la función (si es que retorna algo)

😃

¿Cuáles son las buenas prácticas para escribir Documentación dentro de Python?

Casi tan importante como la escritura de código, es su correcta documentación, una parte fundamental de cualquier programa que a menudo se infravalora o simplemente se ignora. Aparte de los comentarios entre el código explicando cómo funciona, el elemento básico de documentación de Python es el Docstring o cadena de documentación. Simplemente es una cadena de texto con triple comillas que se coloca justo después de la definición de función o clase que sirve de documentación a ese elemento.

Además de esta documentación básica, lo correcto es detallar mejor en el Docstring qué hace y cómo se usa la función o clase y los parámetros que necesita. Se recomienda usar el estilo de documentación del software de documentación sphinx, que emplea reStructuredText como lenguaje de marcado.

Ejemplo de una función bien documentada:

En este ejemplo de la función power() de numpy no solo se explica qué hace la función, sino que indica los parámetros de entrada y salida e incluso da algunos ejemplos de uso.

Con “#” tambien se puede hacer comentarios en el programa

Javadoc /* COMENTARIOS */

En C# se documenta de la siguiente manera

///<summary>
///Lee la configuración de la aplicación desde el disco.
///</summary>
///<return>
///Devuelve true si la configuración fue leida. Si hubo algún error se devuelve false.
///</return>
///<param name="archivo">
///Ruta del archivo en disco a leer.
///</param>

En Python para el tema de comentario sugieren no máximo de 72 caracteres.

Consulta, que diferente hay en documentar con “”" y #?

Lo mejor que pueden hacer es aprender a hacer la documentación desde que comienzan a aprender programación. si no, luego se acostumbran a nunca hacerlo y les terminará costando más trabajo algo que a final de cuentan tienen que aprender sí o sí.

En la uni aprendo Java y la manera de documentar dentro del código es mediante el uso de

/** Descripción del método
*@params
@return
*
*

Así, se puede especificar por ejemplo que hace un método, que parámetros recibe, qué retorna y si es que lanza alguna excepción. Luego mediante javadoc, una utilidad de Oracle, se genera la documentación contenida en un HTML y es ahí donde uno puede ver mediante links como usar ese método.
En Python las buenas practicas indicadas por PEP8 indican que un comentario inicializado con # no debería tener mas de 72 caracteres. También resulta interesante agregar los pasos a seguir para resolver un problema, agregar una descripción con docstrings o simplemente una linea que explique que hace el código.

Recuerden que también podemos utilizar el # para hacer comentarios de una línea y el “”" para hacer comentarios de varias líneas.
Para la documentación es necesario ser:
Conciso y preciso
Explicar los parámetros
Lo que regresa la función

En javascript utilizamos jsdocs, bueno por lo menos intentamos jajajaja y es muy util con vs code, porque al hacer hover te aparece que hace la función, en especial con proyectos grandes es muy útil porqué existen muchas capas de abstracción para realizar muchas cosas relacionadas ya propiamente con la lógica de negocio de un proyecto

_RESUMEN: _

Python Docstring best practices 😃

Un Docstring puede ser de una linea:

Se usa para un resumen corto, conciso y claro. No puede completar más de una linea y siempre debe terminar en un punto(símbolo de puntuación).

También podemos usar Docstring se varias lineas.

Los Docstring de varias lineas consisten en un Docstring de una línea (el resumen), seguido de una línea en blanco, seguido de una descripción más elaborada.

**Tanto para Docstrings mono-linea o multi-linea: **

1. Debe aparecer siempre en la primera sección del método/clase/etc…
2. Siempre Comillas triples (esto facilita su ampliación en el futuro).
3. Siempre dejar una línea en blanco después de cerrar el Docstring.
4. para una función o método debe resumir su comportamiento y documentar sus argumentos, valores de retorno, excepciones generadas, etc.

hay más especificaciones para módulos, clases y subclases.

Todo esto y más lo puedes ver a detalle en la convención oficial de Python
aquí

Nota: _Si violas estas convenciones, lo peor que obtendrás son miradas feas de tus compañeros. Pero algunos softwares (como el sistema de procesamiento de docstring Docutils) conocerán las convenciones, por lo que seguirlas le brindará los mejores resultados. _

Si hay alguna **buena practica general **que me saltado déjala en los comentarios please.

Les comparto un link a una de las fuentes mas importantes de python en temas de estilo y buenas practicas en el cual podran encontrar recomendaciones para sus Documentation Strings entre muchas otras cosas
https://www.python.org/dev/peps/pep-0008/#documentation-strings

Una buena práctica en documentación de código es incluir los docstrings para las funciones, clases y módulos, esto facilita la lectura posterior del código (es mejor leerla en la función, que en un README.md), y facilita la interacción y modificación del código por parte de otros desarrolladores, sean del equipo o no.

Como apunte personal, llevo poco más de 11 años trabajando en infraestructura IT (Ciberseguridad, Servidores, Redes, etc.), y siempre se ha manejado la recomendación, por parte de los gerentes de proyecto, y la he implementado cuando lo he sido, de generar documentación completa y concisa de lo que se desplegó; esto debido a que puede pasar un largo tiempo antes de que se le vuelva a “meter mano” a lo que se instaló, y sea complicado después hacerlo; o en su defecto, no se realice de nuevo dicha administración nunca más, y le sea dificil, si no es que imposible, a otra persona modifiarlo.

hay alguna razon concreta por lo cual no se usa camel case en python o solo por que si?

Ejemplo de documentación en Typescript

Creo que documentar es la mejor practica a la hora de trabajar en equipo 😄

ahhh vea pues de allí es que se crean las descripciones de help.!!

las comillas simples triples ’ ’ 'tambien sirven para comentar nuestro código.

Según lo que yo he aprendido en todo este tiempo, los comentarios en las funciones deberia ser un ultimo recurso y lo principal es tener un buen nombre de funcion y buenos nombres de las variables que a simple vista nos diga que hace la funcion.

Primera clase que no me estalla la cabeza jaja

" Aparte de los comentarios entre el código explicando cómo funciona, el elemento básico de documentación de Python es el Docstring o cadena de documentación, que ya hemos visto. Simplemente es una cadena de texto con triple comillas que se coloca justo después de la definición de función o clase (ver programación orientada objetos, más adelante) que sirve de documentación a ese elemento".

me voló la cabeza, es fundamental

No sabía que se podía hacer desde la terminal!

Muy bueno

Es de muchísima ayuda!
Por más simple que sea mi código, voy a implementarlo siempre

En mi instituto el desarrollo web se hace con php y según lo que he investigado se realiza de la siguiente manera

<php
public function isLoggedIn();
  /**
 * Devuelve la información del usuario sobre la cuenta
 *
 * This method is used to retrieve the account corresponding
 * to a given login. <b>Note:</b> it is not required that
 * the user be currently logged in.
 *
 * @access public
 * @param string $user user name of the account
 * @return Account
 */
  public function getAccount($user = '');
}
?>

Entendido

Que genial!! cada vez me gusta mas python!

Una excelente practica, a aplicarla en todos nuestros programas de ahora en adelante.

Por que n camelcase?

Una duda, porque no existe un estandar en la forma de crear la forma de comentar el código en los lenguajes.

Hola, dejo un articulo para hacerlo en JAVA
https://www.tutorialspoint.com/java/java_documentation.htm

Les comparto la guía de estilos de Python. Básicamente es que hacer y que no cuando uses este lenguaje, espero le spueda ser de ayuda.

https://google.github.io/styleguide/pyguide.html

Excelente buena practica. a aprender a sintetizar la info para poder plasmarla.

Jeje, desde ahora pondré especificaciones a mi código

Hacer eso ahorra mucho tiempo y dinero en el futuro. Así como un adecuado nombre de variables.

y yo que pensaba que con el # en cada línea hacía lo mismo =O

Docstrings: Decimos que hace la función, describimos los parámetros con sus tipos de datos, y indicamos que retornara la función.

Usando el método help() podemos obtener la información de la función

A la documentación que ponemos allí le llamamos docstring y está contenida por triple colons o triple comillas.

Después de terminar nuestro resumen, dejamos un espacio en blanco y al mismo nivel de identación cerramos las triples comillas.

Python:
La documentación de las funciones de Python se realiza mediante cadenas de documentación (“Docstring”). Una cadenas que se incluyen dentro de código para que los usuarios puedan consultarlas mediante la función nativa de Python help(). La cual imprimirá la cadena de documentación del objeto solictado.

Las cadenas de documentación se tienen que incluir inmediatamente después de la línea en la que define el objeto. Para lo que se debe utilizar siempre cadenas de texto con comillas dobles triple, incluso cuando la documentación solamente conste de una línea. Es importante que ninguna de las líneas de la documentación supere los 72 caracteres para que se pueda consultar en terminales.

Excelente clase 😃

Un consejo que me dieron como Una buena práctica es: cada función solo debe realizar una sola actividad, es decir, si tienes un programa para ordenar una lista y encontrar un valor en especifico debes tener dos funciones: una para ordenar y otra para buscar. Así te sera más fácil para ti y para los demás comprender tu código.

Usar buena declaración de variables y funciones puede evitar usar comentarios, pero recuerden el comentario que coloquen debe ser relevante dentro de su código.

Si el código es claro considero que no necesita comentarios

🤖🤖🤖
Documentacion:
La primera linea debe ser un resumen, importante que quepa en una sola linea y este separada del resto de docstrings por un espacion en blanco.
El resto de la cadena de documentación debe describir el comportamiento de la función.
Se recomienda dejar una línea en blanco antes de las triples comillas que cierran la cadena de documentación.
🤖🤖🤖

Buenas prácticas:
Recordar que en Python se maneja la indentación para delimitar bloques de instrucciones. (Hay que ser muy estricto en la sintaxis)
Escribir los programas los más simple posible. (conciso y preciso)

Comentar los programas, explicando el propósito, funcionamiento completo y el resultado esperado.

Al inicio de cada función, agregar brevemente un comentario que explique el comportamiento
general de la función.
Definir el nombre de funciones, variables y constantes que mejor representen el contenido que
almacenarán.
No usar variables cuyo nombre carezca de significado descriptivo. Con un código legible y
nombres significativos, el código se va auto documentado.
Declarar variables en líneas separadas, posibilitando agregar una descripción de cada variable
mediante comentarios.
Definir el nombre de funciones, módulos y clases que mejor representen las acciones que
realizan.
Definir el tamaño de las sangrías para que sean regulares (consistentes) y no varíen a lo largo
del código, es decir, si el primer bloque ocupa como indentación una tabulación, el resto de
bloques deben ser indentados con una tabulación adicional por cada nivel, con eso se facilita la
lectura en cualquier editor de código.
Ser consistente al momento de utilizar un estándar para nombres largos, por ejemplo para una
variable que almacena cantidad de alumnos 'contador_alumnos’
Comentar cuando sea justo y necesario, usar los comentarios dentro de las funciones para
describir las variables (sólo cuando su utilidad sea potencialmente dudosa) y cuando existan
bloques de código difíciles de entender a primera vista; el exceso de comentarios vuelve ilegible
el código.
Definir variables locales al inicio de la implementación de cada función, como un bloque de
código bien separado del bloque que contenga las instrucciones ejecutables, ésta separación
puede consistir en una línea en blanco, o bien un comentario que denote la utilidad de cada
bloque.
Evitar la incorporación de más de una instrucción por línea. Esto reduce notoriamente la
legibilidad del código, ya que el programador habitualmente está acostumbrado a leer una
instrucción por línea.
Realizar la indentación necesaria, si una instrucción abarca más de una línea.

Los docstrings son trozos de documentación que añadimos en nuestro código para especificar que hace esta función.

• Deben tener una descripción corta y clara de lo que hace.
• Se inician con triple comillas doble “”" “”"
• Se describen los parámetros de la función y que tipo son.
• Al final se especifica que resultado retorna.

Les dejo mis apuntes de la clase donde explico más a fondo los docstrings
Apuntes

Documetación oficial sobre las convenciones para docstrings en python:
https://www.python.org/dev/peps/pep-0257/

yo encontré esta extensión y me pareció realmente sencilla y buena

Genial! A mi me encanta usar los doc strings, en PHP se escriben encima de las funciones con la sintaxis:

/** 
* Descripción
*
* Parámetro a
* Parámetro b
* @return value
*/

Si no mal recuerdo era algo así xD

Para conocer la documentación de una función usamos:
help(nombre_función)

1- Breve descripción (que es lo que hace)
2- que acepta como entrada
3- que devuelve

Una buena práctica que me han recomendado varios conocidos que trabajan en programación es escribir el código en inglés. Los comentarios, nombres de las variables, funciones… Todo en inglés.

[2:22] Implementación en código: se incluye justo después de definir la función al comienzo del bloque de código. Debe ir debidamente indentado.

[0:24] Instrucciones o comentarios definidos por triple doble comilla. Debe incluir: 1. Que hace la función. Debes ser conciso y preciso. 2. Que significan los parámetros y cuál es el tipo del parámetro y que estamos esperando con estos parámetros. 3. Que es lo que regresa esta función.

Docstrings
En Python todos los objetos cuentan con una variable especial llamada doc gracias a la que podemos describir para qué sirven y cómo se usan los objetos. Estas variables reciben el nombre de docstrings, cadenas de documentación.

Para comentar en Kotlin:

/**

• Sum two values
• @param a any [Int]
• @param b any [Int]
• @return the sum of the values
  */
  fun sum(a: Int, b: Int): Int
  Los corchetes generan un URI que te lleva a el archivo de esa clase.

Lo mejor que puedes hacer es crear modularidad y Programación Orientada Objetos. No solo en Python. En todo lenguaje de programación

Excelente. Esto es lo que se llaman Buenas Prácticas de Programación.

No lo sabía muy bueno!

Existe algo similar en JS?

interesante desde el punto de vista de buenas practicas

en C# usamos // * *// para documentacion

Especificaciones del código

La especificacion del código es un comentario en el que informamos de forma explicita y concisa lo que realizan nuestras instrucciones. Tenemos que tener 3 items importantes en la documentación:

1. Que hace la instrucción.
2. Que significan los parametros.
3. Que es lo que devuelve nuestra instrucción.

def suma(a, b):
    """Suma dos valores a y b

    param int a cualquier entero
    param int b cualquier entero
    returns la sumatoria de a y b
    """

    total = a + b
    return total

Tema muy importante para poder trabajar en equipo, especialmente si es trabajo remoto.

Dejo un aporte a un buen articulo sobre documentacion https://realpython.com/documenting-python-code/

Recuerden:

• Los comentarios # Indican que hace una parte de nuestro codigo, podemos agregar en cualquier parte del mismo

• Los docstrings “”“indican como una funcion u objeto hace algo y que resultado esperamos”""

Esa sí que no la sabía, he estado usando Camel Case en Python jejeje

Para funciones se puede agregar una r seguido de las comillas para que al momento de poner el cursor sobre una función que estamos llamando nos de su descripción:

def enumeracion(objetivo):
    r'''
    objetivo: int = Número del que se desea obtener su raiz cuadrada
    '''
    respuesta = 0 #Inicialización
    ite = 0
    instanteInicial = datetime.now()

https://www.clubdetecnologia.net/blog/2019/buenas-practicas-en-python/

Encontré este articulo, aunque es documentación basada mas a deploy y esas cosas

Me gusto mucho la forma en que Python documenta las funciones 😲

este curso es muy importante para leer e interpretar y saber muy bien lo que estas haciendo, y lo peor de todo es que me da sueño y no presto mucha atencion , lo voy a tener que ver y ver hasta que lo entienda bien

A un nivel más fundamental hay otra diferencia aún más grande entre los docstrings y los comentarios, y ésta tiene que ver con la intención:
Los docstrings son documentación, y sirven para entender qué hace el código.
Los comentarios sirven para explicar cómo lo hace.

python -m pydoc <lo-que-queremos-saber>

Es el comando por terminal que nos ofrece python para buscar información en Window.

Especificaciones del código
El docstring es la documentación de cual es el funcionamiento de una pieza de código y en Python consta de 3 partes:
• Se da una explicación muy muy muy precisa de que es lo que hace la función.
• Se especifica que significa cada uno de los parámetros(nombre, tipo y que es lo que se espera)
• Al final se especifica que es lo que retorna la función.
Para añadirle un docstring a nuestra función lo que debemos de hacer es en la primera línea del cuerpo de nuestra función añadir un comentario multilínea (usando triple doble comilla “””) y añadir como comentario los 3 pasos ya mencionados.
En Python podemos utilizar la función predefinida help() y pasándole como argumento cualquier otra función, incluso las que nosotros mismos hayamos creado (siempre y cuando les hayamos colocado un docstring) nos mostrara la documentación sobre la función.
Por ejemplo si queremos saber como funciona la función int podemos ejecutar help(int) y nos mostrara la siguiente documentación

The docstring for a module function should include the same items as a class method:

• A brief description of what the function is and what it’s used for.
• Any arguments (both required and optional) that are passed including keyword arguments.
• Label any arguments that are considered optional.

Les dejo una extensión muy buena para VSC que ayuda con el

docstring
https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring

“”“gracias”""

“”" Primero: que hace la función (conciso y preciso).
Segundo: parámetro (nombre, tipo, y que esperamos).
Tercero: que es lo que regresa la función.
"""

no es un lenguaje, pero en html los comentarios son asi:

<!– Aqui va el comentario    –> 

a lo mejor le sirve a alguien

Nunca había escuchado de esa forma de documentar y obtener información gracias.

docstring =! comentarios?

¿El docstring siempre va dentro de la función? no se puede hace antes de la función como se hace en java

Excelente resumen

Ctrl + / en CUALQUIER es el atajo de teclado UNIVERSAL para comentar una línea de código escrita.
Este atajo funcionará en cualquier lenguaje de programación y en cualquier IDE o editor de código

¿exite algo cómo los docstrings en C#?

Muy importante la documentación.

Buenas practicas. Excelente clase.

Aparte de usar Docstrings, existen otros programas o herramientas como pytest, PEP8 y Git o bien, hacer un refactoring sirven para mejorar el código en Python.