Documentación
Clase 23 de 26 • Curso de Patrones de Diseño y Buenas Prácticas en PHP
Contenido del curso
Miguel Jimenez
student•
hace 6 años
Bernardo Aguayo Ortega
student•
hace 6 años
José Gregorio Block
company_admin•
hace 6 años
Clase 23 de 26 • Curso de Patrones de Diseño y Buenas Prácticas en PHP
Contenido del curso
Miguel Jimenez
Bernardo Aguayo Ortega
José Gregorio Block
María Sierra
Rolando Mamani Salas
Florencia Córdoba
Jheysson MacLop
Luis Alejandro Vera Hernandez
Sergio Estrella
Bernardo Aguayo Ortega
Carlos Eduardo Gomez García
Rolando Mamani Salas
Kenet Andrés Chungandro Montenegro
Juan Esteban Galvis
Rolando Mamani Salas
Nicolás Arias
Daniel Hurtado
Christian David Sánchez
Moisés Cedeño
Mauro Chojrin
Xavier Alexandro Basir Jeffrey
Christian David Sánchez
Efraín Hernández García
Juan Esteban Galvis
Rolando Mamani Salas
Carlos Eduardo Gomez García
Juan Pablo Campuzano Monsalve
Byron Marroquin
Eduardo Reyes
Alberto Vargas
Oscar Fuentes Esteves
Fabiola Dayana Acarapi Alvarez
Juan Pablo Celiz
Danny Velásquez
Documentación
¿Qué documentar?
Lo mínimo que necesita las personas que quieren colaborar o heredar tu proyecto.
¿Como documentar?
¿Dónde documentar?
- Wiki
- Ficheros externos.
- README
¿Cuándo documentar?
Gracias Migue!!!
#Gracias!
Documentación
Una buena práctica cuando se trabaja en equipo es documentar. Se trata de dejar por escrito las decisiones que hemos tomado, como está funcionando el código, etc.
¿Qué documentar?
¿Cómo documentar?
¿Dónde documentar?
¿Cuándo documentar?
Muchas Gracias por el resumen
sin embargo cuando se hace desarrollo web, dentro del html/javascript/css no es recomedable tener cosas comentadas ya que primero revela información que no debería tener el usuario y segundo queda desprolijo. Simplemente con el inspector de código del navegador se podría ver todo eso
Para eso se debe limpiar todo eso para el render final de forma automatizada.
y como se documenta en ese caso?
Un lugar donde se puede tener la documentación es en un README de nuestros repositorios en GitHub. Puedes aprender a cómo escribir unos buenos README's en éste enlace ;)
ufff, genial Sergio. Gracias
La documentación en el código me encanta, cuando descubrí que VS Code tomaba la descripción de esos comentarios empecé a usarlos, pero claro, hay que respetar el formato mostrado para que funcione, sin duda la documentación en la mejor manera de entender qué hace el código:D!
Gracias
Para GitHub pueden crear su documentación de sus repositorios en la sección "Wiki", comparto este vídeo al respecto: https://www.youtube.com/watch?v=RhydZnn7Zqc
Aunque un buen archivo README siempre es importante para encontrarse con la información necesaria a primera vista, para editar y agregar distintos elementos al README comparto ese sitio / editor: https://pandao.github.io/editor.md/en.html
Muchas Gracias lo vere despues de este video
La documentación debe hacerse pensando en quien la va a leer.
También pensando en nosotros mismos a futuro en caso de que no tengamos pensado compartir el código, ya que si bien podemos conocer todo el codigo mientras trabajamos en él, solo basta unas cuantas semanas para olvidar muchas cosas y perder tiempo viendo que hace cada cosa si no tenemos bien documentado
debemos pensar en conjunto, tanto para nosotros como para el "prójimo"
mchojrin, ¿Algunos consideran que UML ha muerto? ¿Qué opinas?
Usualmente no coincido con ese tipo de afirmaciones tan categóricas... en informática es raro ver que algo muera (Fíjate que todavía hay gente programando en COBOL :p).
Respecto del UML, lo veo como un rejunte de muchas metodologías... personalmente uso algunas partes (Diagrama de clases a veces lo uso, de actividades también) pero no todo.
Puedes usarlo con tranquilidad :)
Yo en lo personal creo que no ha muerto, siempre me ha parecido algo muy importante para abstraer mejor nuestro proyecto y definir bien las funcionalidades de este.
Una buena documentación ofrece:
La documentación podría estar dentro del README del repositorio
Es una opción y diría yo que la mas utilizada. Pero GitHub también cuenta con la opción "Wiki" para documentar. Encontré este vídeo sobre el tema: https://www.youtube.com/watch?v=RhydZnn7Zqc
Los metodos mas basicos como Getters y Setters o metodos que se entienden a siemple vista igual se tiene que documentar ?
De preferencia sí, aunque no suele ser necesario. Claro, igual depende de qué entiendas tú por "se entienden a simple vista", porque tú podrías entender uno a simple vista, pero tal vez otra persona no 👀
Buenas prácticas
Pull Request al momento de realizar una contribución a la rama principal
Documentación
Es lo mejor que podemos de hacer para el siguiente desarrollador que coja el código que nosotros dejamos o para quienes quieran aportar al código.
Existen varios tipos de documentación y todos igual de importantes. La documentación dentro del código, la documentación escrita acerca del proceso y la lógica del programa y la documentación visual.
¿Cuándo documentar?
Lo ideal sería hacerlo mediante se realiza el código. Sin embargo, no siempre se puede hacer a la par del código pero siempre es importante hacerlo.
🍃 Documentar es una de las mejores prácticas que podemos hacer cuando estamos en un equipo de trabajo. Dejar por escrito cómo hemos hecho algunas funcionalidades, cómo podría ser mejorado el código y por sobre todo debemos dejar comentarios en el código que ayuden a las personas a ubicarse en qué parte de la aplicación están y qué hacen esas líneas de código.
Además de ayudar a las personas a ubicarse en el código y entender su funcionalidad, la documentación de código también tiene otros beneficios. Por ejemplo, puede facilitar el proceso de depuración de errores ya que permite a los desarrolladores rastrear y solucionar problemas más rápidamente. Asimismo, la documentación puede ser útil para futuros miembros del equipo que se unan al proyecto, ya que les permite comprender rápidamente cómo funciona el código y qué decisiones de diseño se tomaron en el pasado. En general, la documentación es una herramienta valiosa para mejorar la calidad del código y la eficiencia del equipo de desarrollo.
Unified modeling language
El UML (Lenguaje de Modelado Unificado) es una herramienta de modelado visual que se utiliza para describir y diseñar sistemas de software. Se utiliza para representar los diferentes aspectos de un sistema, incluyendo su estructura, comportamiento y arquitectura. El UML consta de varios tipos de diagramas, como diagramas de caso de uso, diagramas de clases, diagramas de secuencia y diagramas de estado, que se utilizan para representar diferentes aspectos del sistema. Cada tipo de diagrama se utiliza para modelar un aspecto diferente del sistema y proporciona información valiosa para los desarrolladores y otros miembros del equipo de desarrollo de software.
Herramientas de documentación
Existen diversas herramientas para la documentación de código, algunas de ellas son:
Estas herramientas te permiten generar documentación a partir del código fuente y facilitan la tarea de mantener actualizada la documentación.
Guía de sintaxis para documentar en el mismo código (específicamente para PHP): https://docs.phpdoc.org/guide/references/phpdoc/basic-syntax.html#basic-syntax
Con que esta es la famosa documentación de los memes Devs que nadie realiza... Pensé que era más complejo, es decir, casi casi un manual del código.
No se ve tan difícil o sí?
Estos cursos les puede ayudar: Curso de Programación Orientada a Objetos: POO Curso de Introducción al Technical Writing y Documentación de Código
Que cosa del mal el código con malos identificadores y sin comentarios 😣
Gracias por este completo curso Mauro!