Cómo presentar código a un colega

¿Cómo se presenta la base de código, que puede ser bastante compleja y enredada con muchas "trampas" para un nuevo miembro de su equipo?

Creo que la forma más fácil sería tener la arquitectura general presentada con diagramas y tomar un par de semanas (o meses) dando a la nueva persona tareas bien definidas (y bien definidas) a medida que se acostumbra al código.

Sin embargo, como consultor (y empleado menor, por cierto), no siempre puedo tener eso debido a limitaciones de tiempo o designaciones de roles de equipo. (He estado en este proyecto en particular el doble de tiempo que cualquier otro, por lo que "junior" de ninguna manera "sabe menos sobre el código / proyecto").

Me han encomendado varias veces presentar un nuevo miembro al proyecto y al código, y lamentablemente cada vez que encuentro que no soy mucho mejor que el anterior. Me encantan los diagramas y las imágenes, pero a menudo siento que no explican adecuadamente la complejidad de un sistema. (¿Qué pasa con todas las "trampas" de los pequeños?)

El proyecto está llegando a un punto en el que se lo entregaremos al cliente, y para hacer las cosas más desafiantes, la persona con la que haré una transferencia de conocimiento está esencialmente fuera de la universidad. (No es que sea mucho mejor al hacer transferencias de conocimiento con desarrolladores senior).

Asisto a un grupo de usuarios una vez al mes y a otras oportunidades a medida que surgen, por lo que no estoy acostumbrado a que me presenten nuevos temas, pero siento que mi capacidad para replicar el intercambio de conocimientos efectivo es lamentablemente inadecuada.

Cualquier consejo sería muy apreciado. Estoy buscando principalmente una guía que pueda seguir. Por ejemplo: ¿Por dónde empiezas? ¿Cómo procedes? ¿Cómo cubre tecnologías o patrones desconocidos por parte del oyente sin tomar todo el día? ¿Dónde se vincula la lógica empresarial con la estructura de código?

¡Gracias!

(Como siempre, no dude en editar la pregunta como mejor le parezca).

El primer paso es, por supuesto, eliminar las "trampas" del código. El código claro, conciso y consistente es más fácil de ingresar, trabajar y depurar.

Por donde empiezas

Le pregunto al recién llegado cómo quiere entrar en la base de código. Todos aprenden de manera diferente. A algunas personas les gusta tener pequeñas tareas para trabajar. A algunos les gusta depurar el código existente. Algunos quieren ver el código ejecutándose para entender lo que hace. Algunos quieren comenzar en el punto de entrada y simplemente navegar. Algunos quieren diagramas de visio ... Ningún patrón establecido funcionará mejor para todos.

¿Cómo cubre tecnologías o patrones desconocidos por parte del oyente sin tomar todo el día?

Los evito Que sean cajas negras hasta que el recién llegado pregunte por ellas. Luego, proporcione la información suficiente para entenderlo, con la pista de que pueden aprender más en su propio tiempo, o preguntar más tarde cuando las cosas generales son más conocidas.

¿Dónde se vincula la lógica empresarial con la estructura de código?

Trato de que no. Casi siempre es mejor que el recién llegado aprenda por sí mismo para que se sienta en su mente en una estructura más natural a su forma de pensar.

Una cosa para recordar es mantener la instrucción corta. Las personas tienden a revisar bastante rápido, por lo que cualquier otra instrucción en ese punto simplemente no se 'pega'. Muéstreles cosas durante 15-60 minutos (diferentes personas tienen diferentes períodos de atención) y luego tómese un descanso de 5-30 minutos para que puedan procesarlo.

En mi experiencia, una buena manera de cerrar la brecha entre la amplia visión general que ofrece un diagrama de arquitectura y los detalles importantes de trabajar realmente con el código es hacer un desglose del sistema, es decir, qué sucede cuando llega una solicitud (para el código del servidor ) o un usuario realiza una entrada (para el código del cliente), luego explica paso a paso todas las capas de código que están involucradas.

Otra forma es una "visita guiada" del código fuente, es decir, revise los paquetes / espacios de nombres / módulos / directorios y explique qué hace el código en cada uno de ellos en general. Por supuesto, esto requiere que el código se establezca de forma algo lógica.

No les estás enseñando el código base, les estás enseñando tu trabajo. No intentes pensar en lo que podrían necesitar, mira lo que realmente necesitas saber al hacer tu trabajo.

Obtenga los últimos meses del historial de seguimiento de errores, historias de usuarios de scrum, informes de estado y confirmaciones de control de fuente. ¿Qué archivos tocaste más? ¿Qué código es más problemático? ¿Qué tareas te llevaron más tiempo? Lo más probable es que, si no lo ha tocado en los últimos meses, no sea tan importante como podría pensar que es.

Mire la pila de impresiones en su escritorio. Verifique el historial reciente de su navegador. Busque los correos electrónicos guardados a los que se refiere con frecuencia, los contactos que usa, los documentos que ha descargado. Algunas de las referencias más útiles que he pasado a otros son las notas que me guardé cuando aprendí o diseñé el sistema por primera vez. ¿Qué material de referencia es más útil para usted ?

A continuación, abra su registro de pedidos conocido. ¿Qué cosas necesitarías investigar para terminar esas tareas? ¿Qué áreas de código probablemente contengan el problema? Transmita esa información como si estuviera tomando notas por sí mismo.

Si se refiere a cuadros o diagramas en su trabajo diario, inclúyalos. Si nunca se ha molestado en hacer uno, probablemente tampoco será tan útil para su sucesor / colega.

Una de las tareas más difíciles cuando se enseña es tratar de ponerse en su lugar. En este caso, usted está en su lugar. Has tu mejor esfuerso.

El trabajo de apoyo es lo mejor, tome un error fácil y guíelo por las áreas donde se encontrará. aprenderán rápidamente cómo encaja el código. Naturalmente, vendrán a hacer preguntas sobre este error y la base de código, pero llegarán allí (y obtendrá un error corregido). A menudo es mucho más fácil resolver las cosas con ejemplos, de manera similar, es más fácil resolver una base de código ejecutándola en un depurador.

Si no está seguro de los cambios en el código (o lo están, por lo general no estaría seguro de mis correcciones de código hasta que esté familiarizado con la base de código), puede revisarlo antes de registrarse.

Por supuesto, sus ideas existentes de vistas generales amplias y diagramas de bloques son primeros pasos esenciales.