Tecnología · 1o de Preparatoria · Desarrollo de Software y Lenguajes de Programación · II Bimestre

Documentación y Comentarios de Código

Los estudiantes aprenden la importancia de documentar el código para mejorar su comprensión y mantenimiento por otros desarrolladores.

• Aprendizajes Esperados SEP
• SEP EMS: Desarrollo de Software
• SEP EMS: Comunicación Técnica

Acerca de este tema

La documentación y los comentarios de código son prácticas esenciales en el desarrollo de software. Los estudiantes de primer grado de preparatoria exploran cómo agregar comentarios claros y estructurados facilita la comprensión del código por parte de otros desarrolladores, incluido ellos mismos en el futuro. Esto incluye explicar el propósito de funciones, variables clave y lógica compleja, alineándose con los estándares SEP de Desarrollo de Software y Comunicación Técnica.

En la unidad de Desarrollo de Software y Lenguajes de Programación, este tema fomenta la sostenibilidad de proyectos al reducir errores en el mantenimiento y mejorar la colaboración en equipos. Los alumnos responden preguntas clave como la contribución de la documentación a la longevidad de un software, la información crucial en comentarios y su impacto en el trabajo grupal. Desarrollan habilidades de comunicación técnica que preparan para entornos profesionales reales.

El aprendizaje activo beneficia particularmente este tema porque las prácticas como revisar código ajeno o documentar en equipo hacen visibles los beneficios inmediatos. Los estudiantes experimentan confusiones al leer código sin comentarios y las resuelven colaborativamente, reforzando la importancia práctica de estas habilidades.

Preguntas Clave

1. ¿Cómo contribuye una buena documentación a la sostenibilidad de un proyecto de software?
2. ¿Qué información es crucial incluir en los comentarios del código para su futura comprensión?
3. ¿De qué manera la documentación impacta la colaboración en equipos de desarrollo?

Objetivos de Aprendizaje

• Explicar la función de los comentarios en la legibilidad y el mantenimiento del código fuente.
• Identificar los elementos clave que deben incluirse en la documentación de una función o bloque de código.
• Comparar la efectividad de diferentes estilos de comentarios para comunicar la intención del programador.
• Crear comentarios y documentación para un fragmento de código existente, mejorando su claridad.
• Evaluar la calidad de la documentación de un programa simple, señalando áreas de mejora.

Antes de Empezar

Introducción a la Programación y Algoritmos

Por qué: Los estudiantes deben tener una comprensión básica de cómo escribir secuencias de instrucciones para que puedan empezar a documentarlas.

Variables y Tipos de Datos

Por qué: Es necesario conocer qué son las variables y cómo se utilizan para poder documentar su propósito y contenido.

Vocabulario Clave

Comentario de código	Texto dentro del código fuente que el compilador ignora, utilizado para explicar la lógica, el propósito o el funcionamiento de una sección del programa.
Documentación técnica	Conjunto de explicaciones y guías que describen cómo funciona un software, cómo usarlo o cómo desarrollarlo, incluyendo comentarios en el código y manuales externos.
Legibilidad del código	Facilidad con la que un ser humano puede leer, comprender y seguir la estructura y lógica de un programa informático.
Mantenimiento de software	Proceso de modificar, corregir y mejorar un programa después de su entrega inicial para asegurar su correcto funcionamiento y adaptabilidad a nuevos requerimientos.

Cuidado con estas ideas erróneas

Idea errónea común

Los comentarios son opcionales si el código es obvio.

Qué enseñar en su lugar

Muchos códigos parecen obvios al escribirlos, pero pierden claridad con el tiempo o para otros. Las revisiones en pares ayudan a los estudiantes a experimentar esta confusión directamente y valorar comentarios que expliquen intenciones y suposiciones.

Idea errónea común

Más comentarios siempre son mejores, incluso si son redundantes.

Qué enseñar en su lugar

Comentaciones excesivas distraen; deben enfocarse en lo esencial. Actividades de galería grupal permiten comparar ejemplos y debatir qué agregar, refinando el criterio de utilidad mediante discusión colectiva.

Idea errónea común

La documentación solo es para programadores expertos.

Qué enseñar en su lugar

Es vital desde el inicio para todos. Proyectos colaborativos muestran cómo principiantes se benefician al leer código documentado, fomentando hábitos tempranos a través de roles rotativos.

Ideas de aprendizaje activo

Parejas: Revisión de Código sin Documentación

Entrega a cada par un fragmento de código sin comentarios. Pídele que intenten entenderlo y modifiquen una función. Luego, agregan comentarios propios y comparan con la versión documentada original. Discuten las diferencias en claridad.

30 min·Parejas

Grupos Pequeños: Documentación de Proyecto Colaborativo

Divide la clase en grupos de 4. Cada grupo escribe un programa simple, como un calculador de promedios. Rota roles: uno codifica, otro documenta, otro prueba. Al final, intercambian proyectos para mantenimiento simulado.

45 min·Grupos pequeños

Clase Completa: Galería de Comentarios Efectivos

Proyecta ejemplos de código bien y mal documentado. La clase vota y justifica preferencias en ronda. Luego, en tiempo real, mejoran un código colectivo agregando comentarios guiados por sugerencias grupales.

35 min·Toda la clase

Individual: Autoevaluación de Documentación

Cada estudiante documenta su propio código de una tarea previa. Usa una rúbrica para autoevaluar claridad y completitud. Comparte uno con un compañero para retroalimentación rápida.

20 min·Individual

Conexiones con el Mundo Real

• Los desarrolladores de videojuegos en estudios como PlayStation o Xbox utilizan extensivamente comentarios y documentación para que equipos grandes colaboren en proyectos complejos, asegurando que cada miembro entienda las partes del código escritas por otros.
• Los ingenieros de software en empresas de tecnología como Google o Microsoft documentan sus algoritmos y funciones para que otros desarrolladores puedan reutilizar, depurar o expandir el código en futuros proyectos, manteniendo la coherencia y eficiencia del ecosistema de software.
• Los equipos que desarrollan aplicaciones móviles para Android o iOS deben documentar su código para facilitar la incorporación de nuevos programadores y para que las actualizaciones futuras se realicen sin introducir errores críticos.

Ideas de Evaluación

Boleto de Salida

Entregue a cada estudiante un fragmento corto de código sin comentarios. Pida que escriban dos comentarios explicando partes clave del código y una frase sobre por qué es importante documentar ese fragmento específico.

Evaluación entre Pares

Los estudiantes intercambian un programa simple que hayan escrito. Cada uno revisa el código de su compañero y responde: ¿Entiendo el propósito de cada función principal? ¿Hay al menos un comentario explicando una parte compleja? Escriben una sugerencia de mejora para la documentación.

Verificación Rápida

Presente en pantalla un ejemplo de código bien documentado y otro mal documentado. Pregunte a los estudiantes: ¿Cuál código es más fácil de entender y por qué? ¿Qué diferencia principal observan entre ambos?

Preguntas frecuentes

¿Cómo contribuye una buena documentación a la sostenibilidad de un proyecto de software?

Una documentación clara reduce el tiempo de onboarding para nuevos desarrolladores y minimiza errores en modificaciones futuras. En proyectos largos, como apps escolares, permite que el equipo mantenga el código sin perder funcionalidad. Esto alinea con estándares SEP al promover software mantenible y escalable.

¿Qué información es crucial incluir en los comentarios del código?

Incluye el propósito de funciones, parámetros de entrada/salida, lógica compleja, suposiciones y cambios históricos. Evita repetir lo obvio. Ejemplos concretos como 'Esta función calcula el promedio ignorando valores nulos' facilitan la comprensión rápida y futura depuración.

¿Cómo puede el aprendizaje activo ayudar a entender la documentación de código?

Actividades como revisiones en pares o documentación colaborativa hacen tangible el caos de código sin comentarios. Los estudiantes resuelven problemas reales en equipo, discuten elecciones y ven mejoras inmediatas en colaboración. Esto construye hábitos duraderos más que lecturas pasivas, alineado con pedagogía SEP.

¿De qué manera la documentación impacta la colaboración en equipos de desarrollo?

Facilita la división de tareas al permitir que cualquier miembro entienda y extienda el trabajo ajeno. En simulaciones grupales, reduce fricciones y acelera iteraciones. Desarrolla comunicación técnica esencial para entornos profesionales, preparando a los alumnos para proyectos reales.