BUENAS 👌 (mejores) PRÁCTICAS de PROGRAMACIÓN en Odoo | Comenta y documenta tu código Python y XML

Buenas Prácticas de Programación: Comentarios en Python y XML

Introducción a los Comentarios

• En este video se abordan las buenas prácticas de programación relacionadas con los comentarios en Python y XML.

• Se menciona el uso del símbolo de almohadilla (#) para agregar comentarios al final de una línea de código, aplicable tanto en Python como en XML.

Tipos de Comentarios en Python

• Los comentarios pueden ser unilínea o multilínea; para estos últimos se utilizan tres comillas seguidas (simples o dobles).

• Se explica que la forma correcta de comentar es esencial para mantener la claridad del código.

Comentarios en XML

• Para comentar en XML, se utiliza la sintaxis <!-- comentario -->, comenzando con un símbolo menor que (<), seguido por un signo de exclamación y dos guiones.

• Esta estructura permite incluir texto explicativo dentro del código sin afectar su ejecución.

Documentación del Código: Métodos y Parámetros

Documentar Métodos

• La documentación adecuada incluye descripciones sobre lo que hace un método y qué valores retorna.

• Es importante detallar cada parámetro, utilizando la palabra "para" seguida del nombre del parámetro y su descripción.

Estructura Estándar para Documentación

• Se debe especificar el tipo de dato retornado usando :return seguido por una explicación si el método devuelve algún valor.

• No todos los métodos retornan valores, así que esta parte no siempre es necesaria.

Validaciones Complejas y Documentación Adicional

Explicaciones Claras

• Es recomendable documentar validaciones complejas dividiendo el código en secciones claras con números para facilitar su comprensión.

• Las variables complejas deben ser documentadas adecuadamente; no todas las variables requieren explicación, solo aquellas cuya función no es evidente.

Ejemplos Prácticos

• Se presentan ejemplos donde se utilizan almohadillas para identificar pasos específicos dentro del código.

Documentación de Código: Mejores Prácticas

Importancia de la Documentación del Código

• La documentación del código es esencial para entender variables, ciclos y consultas. Es una buena práctica documentar el código para que sea comprensible.

• Una mejor documentación facilita a otros desarrolladores modificar o adaptar el código existente, promoviendo un trabajo colaborativo más eficiente.

Comentarios en Código Python y XML

• Además de documentar el código Python, también es crucial comentar secciones importantes en XML. Los comentarios ayudan a describir tipos de pistas y la razón detrás de cada sección.

• Se pueden referir a elementos específicos dentro del código, como un botón o una vista particular, lo que mejora la claridad del mismo.

Ejemplos de Buenas Prácticas en Comentarios

• En ejemplos prácticos, se observa cómo se comentan las secciones del código estándar. Por ejemplo, líneas específicas indican el propósito de cada sección (como mensajes de estatus o contenido principal).

• Es importante eliminar comentarios innecesarios o "basura", como campos y variables no utilizados que quedan comentados al finalizar el desarrollo.

Depuración y Limpieza del Código

• Al entregar la versión final del código, es fundamental depurar y asegurarse de que no queden variables o campos comentados sin utilidad.

• Un ejemplo práctico muestra líneas comentadas que no aportan valor; estas deben ser eliminadas para mantener un código limpio y funcional.

Revisión Final antes de Entregar el Código

• Se debe revisar todos los archivos generados por instrucciones como scaffold, ya que pueden contener mucho código comentado innecesario.

• Archivos creados automáticamente pueden incluir plantillas con códigos sin funcionalidad; es recomendable eliminar estos archivos si no aportan nada al proyecto final.