Mantener la documentación actualizada es uno de los mayores retos en cualquier equipo de desarrollo. CodeStream resuelve este problema con los code marks, una herramienta que genera documentación viva, capaz de evolucionar junto con el código sin volverse obsoleta. A continuación se explican las formas de organizar, relacionar y exportar esa documentación directamente desde el editor.
¿Cómo se crean y relacionan los code marks?
Un code mark se crea seleccionando un bloque de código y haciendo clic en Add Comment [01:10]. A partir de ahí se agrega una descripción que documenta qué debe modificarse o cualquier detalle relevante para el equipo.
Existen tres métodos para organizar la información dentro de CodeStream [01:25]:
- Agregar varios bloques de código al mismo code mark: útil cuando un mismo comentario aplica a secciones distintas, incluso en archivos diferentes. Se usa el botón Add Code Block [01:48] para vincular, por ejemplo, un archivo CSS con un archivo HTML dentro del mismo registro.
- Relacionar code marks entre sí: permite conectar secciones de código que tienen dependencia lógica. Al hacer clic en el ícono de CodeStream aparece la lista de code marks existentes; con la búsqueda se localiza el que se necesita y se enlaza, cambiando a color azul para indicar la relación [02:23]. No hay límite en la cantidad de relaciones.
- Usar tags o etiquetas: se crea una etiqueta —por ejemplo "Standard"— y se aplica a cada code mark relacionado con un mismo tema [03:15]. Después, filtrando por ese tag, se localizan todos los code marks vinculados de forma rápida.
¿Qué sucede cuando el código cambia?
La documentación tradicional se desactualiza con cada commit. Los code marks, en cambio, se mueven junto con el bloque de código al que están asociados [03:50]. Si se corta y pega un bloque en otra parte del archivo, el símbolo azul del code mark lo acompaña.
Cuando se modifica el contenido del bloque, el code mark muestra la indicación "This code is changed" [04:10], alertando de que el código referenciado ya no es idéntico al original. El desarrollador decide entonces si agrega un nuevo comentario o si la anotación sigue siendo válida.
¿Cómo se exporta la documentación fuera del editor?
CodeStream ofrece dos mecanismos para llevar la información a otros contextos.
¿Qué es un permalink y para qué sirve?
Al seleccionar un fragmento de código aparece la opción Get Permalink [04:35]. Se puede generar un enlace público o privado, con o sin el bloque de código incluido. Una vez copiado, se pega en cualquier documento externo —por ejemplo, un Google Docs de inducción— y al hacer clic se abre automáticamente el editor en la ubicación exacta del código referenciado [04:55].
¿Cómo se exportan todos los code marks?
Desde el menú principal, en la sección Team Admin, se encuentra la opción Export Data [05:15]. La información se genera en formato CSV, lista para copiar y pegar en herramientas como Excel o Google Sheets. Esto permite crear guías para desarrolladores, reportes o alimentar otros sistemas de gestión con datos actualizados.
¿Por qué CodeStream es un proyecto open source?
CodeStream es software de código abierto [05:40], lo que significa que cualquier desarrollador puede contribuir, revisar el código fuente y proponer mejoras. Los proyectos open source fomentan la colaboración, el aprendizaje entre pares y la retroalimentación constante, aspectos que impulsan la evolución de la tecnología que utilizamos a diario.
Si ya usas code marks en tu flujo de trabajo, comparte cómo te han ayudado a mantener tu documentación al día.
