Tecnología · 1o de Preparatoria

Ideas de aprendizaje activo

Documentación y Comentarios de Código

Para los estudiantes de primer grado de preparatoria, aprender documentación y comentarios de código requiere práctica activa. Trabajar con fragmentos reales de código, revisando y mejorando su claridad, les ayuda a comprender por qué estas prácticas son esenciales en el desarrollo profesional.

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

• 20–45 min
• Parejas → Toda la clase
• 4 actividades

Actividad 01

• Cabezas Numeradas Juntas
• 30 min · Parejas

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.

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

Consejo de Facilitación

En la actividad de parejas, asegúrese de que los estudiantes trabajen con código que no hayan escrito ellos para evitar sesgos de familiaridad.

Qué observar

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.

• Recordar
• Comprender
• Aplicar
• Habilidades de Relación
• Autogestión

Actividad 02

• Cabezas Numeradas Juntas
• 45 min · Grupos pequeños

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.

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

Consejo de Facilitación

Para la documentación colaborativa, asigne roles específicos (ej: documentador, revisor, editor) para que todos participen activamente.

Qué observar

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.

• Recordar
• Comprender
• Aplicar
• Habilidades de Relación
• Autogestión

Actividad 03

• Cabezas Numeradas Juntas
• 35 min · Toda la clase

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.

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

Consejo de Facilitación

En la galería de comentarios, prepare ejemplos con errores comunes y bien documentados para guiar la discusión hacia criterios claros.

Qué observar

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?

• Recordar
• Comprender
• Aplicar
• Habilidades de Relación
• Autogestión

Actividad 04

• Cabezas Numeradas Juntas
• 20 min · Individual

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.

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

Consejo de Facilitación

En la autoevaluación, pida que los estudiantes comparen su documentación con estándares de claridad técnica antes de entregarla.

Qué observar

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.

• Recordar
• Comprender
• Aplicar
• Habilidades de Relación
• Autogestión

Algunas notas para enseñar esta unidad

Enseñe documentación como una habilidad de comunicación técnica, no solo técnica. Evite enfocarse únicamente en reglas de sintaxis. En su lugar, use ejemplos del mundo real donde la falta de comentarios haya causado errores o retrasos. Los estudiantes aprenden mejor cuando ven el impacto de sus prácticas en equipos reales. La investigación sugiere que la retroalimentación entre pares es más efectiva que las correcciones del profesor cuando se trata de desarrollar criterio propio.

Los estudiantes demuestran comprensión cuando explican el propósito del código, identifican partes que requieren comentarios y proponen mejoras concretas en la documentación. También valoran la importancia de escribir para una audiencia, no solo para sí mismos.

---

Cuidado con estas ideas erróneas

• Durante la actividad de Parejas: Revisión de Código sin Documentación, algunos estudiantes pueden pensar que los comentarios son innecesarios si el código parece claro.

  Durante esta actividad, entregue a cada pareja un fragmento de código que parezca obvio al principio pero que incluya supuestos técnicos implícitos. Pídales que intenten explicar el código al otro sin comentarios y observen dónde surge la confusión. Luego, compararán con versiones documentadas para evidenciar la necesidad de comentarios.

• Durante la actividad de Grupos Pequeños: Documentación de Proyecto Colaborativo, los estudiantes pueden creer que más comentarios siempre son mejores.

  Durante esta actividad, guíe a los grupos para que identifiquen comentarios redundantes en ejemplos proporcionados. Luego, pídales que debatan qué información es esencial y qué puede eliminarse. Esto les ayudará a desarrollar criterio para comentarios concisos y útiles.

• Durante la actividad de Galería de Comentarios Efectivos, algunos estudiantes pueden pensar que la documentación es solo para expertos.

  Durante esta actividad, incluya ejemplos de proyectos colaborativos donde principiantes documentaron código para otros principiantes. Pida a los estudiantes que identifiquen cómo la documentación ayudó a sus compañeros menos experimentados y discutan el valor de documentar desde el inicio.

---

Metodologías usadas en este resumen

• Cabezas Numeradas Juntas