Estuve trabajando en un proyecto hace tres meses, y de repente apareció otro proyecto urgente y me pidieron que cambiara mi atención.

A partir de mañana, regresaré al antiguo proyecto. Me doy cuenta de que no recuerdo qué estaba haciendo exactamente. No se donde empezar.

¿Cómo puedo documentar un proyecto de manera que cada vez que mire hacia atrás no me lleve más de unos minutos ponerme en marcha desde donde me fui? ¿Hay mejores prácticas?

Solo quería aportar algunos consejos que no serán útiles en su situación actual, pero puede comenzar a implementarlos ahora para ayudar en el futuro.

Por supuesto, hay candidatos obvios como listas de tareas pendientes y registros de problemas; mirar los problemas recientemente agregados debería darle una pista de lo que estaba haciendo cuando se retiró del proyecto.

En proyectos anteriores en los que he trabajado, se esperaba que las personas mantuvieran un registro del proyecto como parte del proceso de gestión de calidad. Los contenidos no se especificaron muy claramente, pero la idea era mantener un registro diario de las cosas relacionadas con el proyecto que pudieran ser útiles para el trabajo continuo en el futuro o para revisar las actividades al finalizar; por ejemplo:

• Observaciones sobre la calidad del proyecto.

  este código puede usar alguna refactorización

  hizo una implementación rápida para que esto funcione, pero ABC sería mejor.

• Elementos / problemas de Todo que no desea registrar formalmente en un rastreador de problemas

  "debería hacer que este método funcione, x < 0pero actualmente está fuera de alcance.

• Decisiones de diseño , especialmente las no triviales.

  Nuestra función de clasificación estándar realiza una clasificación rápida, pero eso no conserva el orden de los elementos iguales bajo la condición de clasificación, que necesitamos aquí.

  El algoritmo obvio sería ABC, pero eso falla aquí porque xpodría ser negativo, por lo que necesitamos la forma generalizada ( enlace de Wikipedia ).

• Problemas encontrados y cómo los resolvió. Una muy importante, en mi opinión personal: cada vez que encuentre un problema, anótelo en el registro.

  Revisé el código pero dio el error XYZ0123, resulta que primero tuve que actualizar el componente C a la versión 1.2 o superior.

Los dos últimos puntos son muy importantes. A menudo me he encontrado con una situación o problema similar, a veces en un proyecto completamente diferente, y pensé "hmm, recuerdo haber pasado un día en esto, pero ¿cuál fue la solución nuevamente?"

Cuando regrese a un proyecto después de un tiempo, leer el registro del proyecto (ya sea el suyo o el del desarrollador más reciente) debería volver al flujo que tenía cuando se fue y advertirle sobre algunas de las trampas que de lo contrario puede caer de nuevo.

Las listas de tareas son mágicas. Por lo general, debe mantener una lista de tareas activas para cada proyecto e incluso mientras está ocupado programando, si piensa en algo que debe hacerse y no puede hacerlo de inmediato, se incluye en la lista. Mantenga esta lista en un lugar conocido, ya sea en una hoja de cálculo o en un archivo de texto en la carpeta del proyecto electrónicamente, o en su libro de registro de papel.

Además, cada vez que abandone el proyecto durante la noche (o durante el fin de semana), tome una nota adhesiva y escriba lo siguiente que iba a hacer en la nota, y péguela en el monitor. Eso hace que sea más probable que regrese rápidamente a la mañana siguiente.

Editar :

Debo mencionar que las listas de tareas (listas de tareas priorizadas específicamente segregadas por lugar y proyecto) son una parte clave del libro Getting Things Done , que encontré muy influyente.

¿Qué hacer ahora?

Ahora, a partir de mañana, volveré a mi antiguo proyecto y me doy cuenta de que no recuerdo exactamente qué estaba haciendo y por dónde empezar.

Supongo que no has hecho nada de la siguiente sección. Por lo tanto, buscar una lista de tareas pendientes no funcionará.

1. Bloquear un período de tiempo. Ponga esto en su calendario y dedique tiempo a revisar el proyecto. Esto podría estar revisando documentación, código, requisitos, etc.
2. Acepte que tomará un tiempo volver a la velocidad. Asegúrese de que todos los involucrados se den cuenta de esto. Asegúrate de darte cuenta de esto.
3. Comience con una pequeña tarea. Reconstruye tu confianza haciendo algo pequeño. Si tiene una lista de elementos nuevos, primero revise los más pequeños. Esto no solo reconstruye su confianza sino que también le ayuda a familiarizarse con el proyecto.

¿Cómo mejorar esto para ti en el futuro?

¡Deseo saber cómo documentar el proyecto de modo que cada vez que mire hacia atrás no me tome más de unos minutos para ir desde donde me fui!

Primero, debe tener un sistema para realizar un seguimiento de todos. ¿Tienes ese sistema ahora? ¿Cómo gestionas tu proyecto actual?

Podría ser atropellado por un autobús mañana y mi equipo tendría una buena idea de más del 90% de mis artículos de acción. Esto se debe a que tengo un sistema coherente para documentar mi:

• Todos inmediatos (<artículos de 1 semana)
• "Es bueno tener" todos
• Hitos y macro todos (donde los detalles no son significativos)
• Requisitos / notas de la reunión

Además, uso un VCS y comento mi código cuando corresponde.

Esto funciona para mí y para mi equipo, ya que soy el desarrollador principal. Puede usar algún tipo de sistema de seguimiento de problemas para un equipo. O un retraso cuando se trabaja con Agile. Hay un montón de opciones. Si está realmente interesado en esto, lea sobre Cómo hacer las cosas u otras metodologías relevantes de gestión de tareas, que existen casi precisamente por lo que describe.

¿Cuál es el punto de?

Los detalles del sistema son menos relevantes que el hecho de que es un sistema cohesivo y que lo usa . Y que lo uses. Y úsalo. Esto es importante. Más importante que un buen sistema perfecto que no uses. No hagas "bien, la mayor parte de mi trabajo está aquí, pero algo está en mi cabeza" o odiarás volver a un proyecto.

Además, asegúrese de que sus comentarios expliquen "por qué" en lugar de solo el "qué" para el código. Es mucho más fácil leer "esto es corregir un error con IE8" y recordar lo que hace el código que un comentario simplemente explicando los detalles técnicos.

En mi opinión, hay dos partes para "reanudar" un proyecto de código:

1. Determinar dónde lo dejaste
2. Recordando lo que te queda por hacer

Esta es una de esas cosas que, creo, si está haciendo el control de versiones de la manera correcta, será su "otro cerebro".

¿Dónde dejaste ? Siempre que confirme código con frecuencia, observe su último conjunto de cambios. Lo más probable es que active algo en su mente. Si no, mira los últimos, comenzando con los commits más antiguos y repitiendo.

En cuanto a lo que te queda por hacer , un trabajo atrasado debería servir para ese propósito (o una lista de tareas pendientes, o lo que quieras nombrar. Básicamente elementos para el futuro).

No soy un desarrollador de software a tiempo completo. Soy un programador que piratea las noches y los fines de semana. Debido a esto, cuando el trabajo u otras cosas que no son de programación tienen mayor prioridad, a veces puedo pasar días y semanas sin siquiera extraer mi código de un vistazo. Lo anterior ha demostrado ser bastante efectivo.

Esto no pretende ser una respuesta completa, ya hay varias muy buenas que mencionan cosas importantes como cómo usar su VCS y su software de gestión de proyectos, sino más bien un anexo que agrega algunos puntos que no vi en ningún otro, que yo es muy útil y espero que otras personas también lo encuentren útil.

1. Ninguna tarea es demasiado pronto o demasiado pequeña para escribir

Las personas generalmente hacen listas de TODO para las cosas que planean hacer en el futuro , pero dado que la programación requiere concentración, y dado que podemos interrumpirnos en cualquier momento , he encontrado útil escribir incluso lo que estoy haciendo ahora, o lo que estoy a punto de comenzar en cuestión de segundos . Usted puede sentir que estás en la zona y que posiblemente no podría olvidar la solución que sólo le golpeó en que aha momento, pero cuando su compañero de trabajo se reduce en el cubo se puede mostrar la imagen de un dedo del pie infectado , y que está solo capaz finalmente de deshacerse de él comenzando a roer su propio brazo , es posible que desee haber escrito una nota rápida, incluso si solo en una nota Post-It ™.

Por supuesto, algún otro medio más persistente podría ser mejor (me gusta especialmente OmniFocus ), pero el punto es tenerlo en algún lugar , incluso si terminas en 20 minutos y luego tiras el Post-It ™. Aunque puede descubrir que esa información se vuelve útil, para poner hojas de tiempo o facturas para el cliente, o cuando su jefe / cliente le pregunta en qué ha estado trabajando y no puede recordarlo. Si suelta todas estas notas en una caja, un cajón o una carpeta, cuando se produce una gran interrupción (un proyecto de interrupción), puede echar un vistazo y recordar muchas de las cosas que hizo para llevar su código al punto donde encuéntrelo cuando regrese al proyecto.

2. Use una pizarra blanca en su escritorio para capturar ideas generales

Tengo una pizarra blanca de 3 "x 4" al lado de mi escritorio, así que cuando comienzo un proyecto puedo hacer una lluvia de ideas sobre las soluciones a todos los problemas que percibo en un proyecto. Podrían ser diagramas arquitectónicos, casos de uso, listas de riesgos y obstáculos, o cualquier cosa que le parezca relevante.

Algunos enfoques más formalizados requieren que genere diagramas y casos de uso, entre otros, como "entregables" en algún formato en papel o electrónico, pero creo que eso puede crear mucho trabajo adicional, y simplemente convertirse en una serie de subproyectos que terminan divorciarse del propósito real del proyecto principal, y solo parte de un proceso formalizado que tiene que hacer pero al que nadie le presta mucha atención. Una pizarra es lo más simple que realmente funciona, al menos en mi experiencia. Es tan persistente como desee (con una cámara) y lo más importante le permite obtener sus ideas de inmediato.

Creo que es mejor con un bolígrafo en la mano, por lo que arrojar mis pensamientos sobre una superficie blanca es algo natural para mí, pero si no encuentra que ese sea el caso para usted, aquí hay algunas preguntas que pueden ayudarlo a decidir qué es relevante :

• Si yo fuera el desarrollador principal, a punto de irme de luna de miel durante 3 meses mientras otros desarrolladores completaban el proyecto, ¿qué dirección general me gustaría darles? ¿Qué ideas desearía asegurarme de que conocieran, o qué enfoques desearía asegurar que tomaron? ¿De qué bibliotecas u otras soluciones útiles me gustaría estar seguro?
• Si este proyecto fuera mi idea de un millón de dólares que sabía que garantizaría mi futura independencia financiera, pero estaba programado para una cirugía crítica que me incapacitaría durante 3 meses, ¿qué me gustaría que tuviera mi futuro yo para asegurar la finalización exitosa de ¿el proyecto?

(Cuando escribo las ideas por primera vez, solo me preocupa que tengan sentido para mi ser actual. Una vez que están abajo, puedo mirarlas de manera más crítica y hacer cambios para asegurarme de que tengan sentido para mi futuro o para los demás. Preocuparme demasiado acerca de comunicarse con los demás a medida que los escribe inicialmente puede conducir al bloqueo de los escritores: una mente obstruida por objetivos en competencia. Bájela primero; preocúpese por la claridad más tarde).

Le recomiendo que gaste el dinero para comprar una pizarra decente, al menos 3 "x 4", y colgarla en el espacio donde normalmente trabaja. Hay muchas ventajas de una pizarra física sobre cualquier sistema virtual.

• Es largo. Al ocupar mucho espacio, hace sentir su presencia, y los planes en él se sienten como parte de su espacio de trabajo, lo que ayuda a orientarlo en la dirección correcta todo el tiempo.
• Está allí de manera persistente: no tiene que iniciar una determinada aplicación o sitio web para acceder a ella, y no se arriesgará a olvidar cómo acceder a ella, ni a que esté allí.
• Es inmediatamente accesible cuando tiene una idea en la que desea pensar.

Pierde muchos de los beneficios si solo usa una pizarra en una sala de reuniones y luego toma una instantánea con su teléfono. Si gana dinero programando, vale la pena el costo de una pizarra decente.

Si usted tiene otro proyecto interrumpir la que ha llenado su pizarra, puede que tenga que recurrir a la instantánea en su teléfono, pero al menos tendrás que en 3 meses cuando se termine el proyecto "urgente" y usted tiene que volver al otro. Si desea volver a crearlo en su pizarra, probablemente solo le tomará 15 minutos, y puede descubrir que puede mejorarlo mucho en el proceso, lo que hace que esa pequeña inversión de tiempo valga la pena.

3. Informar a los interesados ​​sobre el costo de interrumpir un proyecto.

La metáfora de un avión me parece útil: comenzar y completar un proyecto es como volar un avión. Si se rescata a la mitad del vuelo, el avión no solo se quedará sentado en el aire esperando que regrese, y necesita alguna forma de viajar desde el proyecto / vuelo actual al siguiente. De hecho, si estás en medio de un vuelo de Phoenix a Fargo y te dicen que debes interrumpir ese vuelo para tomar otro avión de Denver a Detroit, tendrás que aterrizar el primer avión en Denver (que afortunadamente no está lejos de su ruta de vuelo (no siempre es el caso con interrupciones reales) y alguien tiene que averiguar qué hacer con la carga y los pasajeros. No se quedarán sentados y esperarán por siempre.

El punto de esto para los proyectos es que la transición de un proyecto a otro conlleva un gran gasto de tiempo y deja muchos extremos perdidos que deben ser tratados.

En un proyecto, obviamente e inevitablemente sucede mucho en su cabeza mientras trabaja, y no todos los pensamientos pueden ser serializados en un medio escrito, y no cada ápice de esos pensamientos que se serializan permanecerán cuando se deserialicen. Aunque podemos capturar parcialmente nuestros pensamientos por escrito, es un formato con muchas pérdidas.

El problema (como lo veo) es que los gerentes de proyectos y otras personas de negocios piensan en los proyectos como una serie de pasos que a menudo se pueden reordenar a voluntad (a menos que haya una dependencia explícita en su diagrama de Gantt) y se puedan distribuir fácilmente entre las personas o retrasado hasta que sea más conveniente para el negocio.

Cualquiera que haya realizado alguna cantidad de programación sabe que los proyectos de software no pueden tratarse como bloques de Lego para moverse de la forma que desee. Creo que la metáfora de los viajes aéreos al menos les da a las partes interesadas algo concreto en lo que pueden pensar que claramente no puede tratarse como una serie de pasos dispares que deben reordenarse por capricho. Al menos, facilita la comprensión de su punto de que hay un costo por tales interrupciones. Por supuesto, sigue siendo su decisión, pero debe informarles antes de que interrumpan un proyecto para darle otro. No seas combativo, pero ofrece información útil y la perspectiva útil del desarrollador, listo para hacer lo que necesiten de ti, pero solo ofreciéndoles información que tal vez no conozcan si no les dices.

En breve:

1. Escriba todo lo que está a punto de hacer, incluso si no cree que alguna vez podría necesitarlo. Incluso un lápiz corto supera un recuerdo largo.
2. Haga una lluvia de ideas sobre el panorama general en una pizarra física a la que tiene acceso persistente.
3. Usted puede evitar interrupciones del proyecto si se hace responsables de las decisiones conscientes de que hay un costo de tales interrupciones, y al menos tendrá que establecer las expectativas para que sepan el proyecto tomará un poco más cuando se reanude.

Puede consultar el historial del proyecto en su software de control de versiones de hace tres meses. Lea sus mensajes de confirmación y las diferencias más recientes para tener una idea de en qué estaba trabajando.

El uso de un sistema de control de fuente con estrategias adecuadas de ramificación y fusión, junto con un sistema de seguimiento de problemas (como Redmine o GitHub ) lo ayuda a compartimentar los cambios que ha realizado, darles dirección y documentar su 'contexto' perdido como Una parte natural del flujo de trabajo.

1. Antes de comenzar un cambio de código, asegúrese de que haya un 'problema' registrado en su sistema de seguimiento de problemas. Eso cubre la parte faltante de "qué estaba haciendo" de su trabajo.
2. Cree una rama en su sistema de control de código fuente y asegúrese de que sus cambios en esa rama estén SÓLO relacionados con el problema mencionado anteriormente. Esto lo ayudará a aislar los cambios y le dará un historial del cambio, respondiendo a la pregunta "¿dónde lo dejé?" una vez que vuelvas a trabajar en eso más tarde.
3. Una vez que haya terminado con el cambio, vuelva a fusionarlo en su troncal y cierre el problema.

Hay muchas respuestas largas. Este es un breve acerca de lo que más me ayuda:

• Código limpio
• Código limpio
• Código limpio
• Control de versiones (diffs y commit comments).
• Una nota Post-It o una Lista de Todo o un Kanban-Board (ver, por ejemplo, Trello y Evernote)

Sin embargo, Diffs, Commit comments, Post-It notes, Todo-Lists o Kanban-Board pueden malinterpretarse con el tiempo por falta de contexto. Así que aquí está lo más importante:

CÓDIGO LIMPIO

¿Cómo puedo documentar un proyecto de manera que cada vez que mire hacia atrás no me lleve más de unos minutos ponerme en marcha desde donde me fui?

En primer lugar, esto implica que hay una descripción de alto nivel y una estructura de código en el proyecto que puede comprender fácilmente en unos minutos, a diferencia de un trillón de líneas de código sin estructura aparente y sin comentarios.

¿Hay mejores prácticas?

Las siguientes son las mejores prácticas que adopté a lo largo de una carrera de más de 20 años en proyectos muy pequeños a muy grandes y me han servido bien a mí y a mis equipos. Solicite en el orden listado a medida que su proyecto crece

1. Utilice el control de versiones para obtener un registro gratuito de lo que sucedió, cuándo y quién aplicó los cambios. También le permite recurrir fácilmente a una versión anterior en cualquier momento.

2. Modularice su código (dependiendo del lenguaje y el entorno de programación, use clases, módulos, paquetes, componentes).

3. Documenta tu código. Esto incluye documentación resumida en la parte superior de cada archivo (¿qué hace esto? ¿Por qué? ¿Cómo usarlo?) Y comentarios específicos a nivel de funciones, procedimientos, clases y métodos (¿qué hace? Argumentos y valores de retorno / tipos? efectos secundarios?).

4. Agregue TODOy FIXMEcomente mientras está codificando. Esto ayuda a recordar los porqués y las peculiaridades que inevitablemente ingresarán a su base de código y que más tarde tendrá que preguntarle a WTF. . P.ej:

   //TODO shall actually compute X and return it
   ... some code that does not compute X yet (maybe returns a fixed value instead)
   
   //FIXME make this constant time instead of n^2 as it is now 
   ... some code that works but is not efficient yet
   

5. Acostúmbrese a dibujar diagramas para documentar la estructura y el comportamiento complejo, como secuencias de llamadas entre módulos / objetos / sistemas, etc. Personalmente, prefiero UMLet, ya que es rápido de usar, crea buenos gráficos y, lo más importante, no se interpone en su camino . Pero, por supuesto, debe usar cualquier herramienta de dibujo que encuentre que hace el trabajo. Recuerde que el propósito de cualquiera de estos dibujos es comunicarse de manera sucinta, no especificar un sistema en minucioso detalle (!!).

6. Agregue pruebas unitarias desde el principio. Las pruebas unitarias no solo son excelentes para las pruebas de regresión, sino que también son una forma de documentación de uso para sus módulos.

7. Agregue documentación externa de código desde el principio. Comience con un archivo README que describa las dependencias necesarias para ejecutar y desarrollar el proyecto, cómo instalarlo y cómo ejecutarlo.

8. Acostúmbrate a automatizar tareas repetitivas . Por ejemplo, los ciclos de compilación / compilación / prueba deben tener una secuencia de comandos (por ejemplo, en uso de JavaScript grunt, en Python fabric, en Java Maven). Esto lo ayudará a ponerse al día rápidamente cuando regrese.

9. A medida que su proyecto crezca, agregue más documentación generando documentos de código fuente (utilizando algún tipo de comentarios de estilo JavaDoc y una herramienta adecuada para generar HTML o PDF a partir de él).

10. Si su proyecto crece más allá de un solo componente y tiene una implementación más compleja, asegúrese de agregar documentación de diseño y arquitectura . Una vez más, tenga en cuenta que el propósito de esto es comunicar la estructura y las dependencias en lugar de detalles minuciosos.

Además de las sugerencias sobre el seguimiento del proyecto, listas de tareas pendientes, Trello, etc., algo que leí una vez que ayuda si está practicando TDD es alejarse siempre de su proyecto con una nueva prueba fallida para implementar cada vez que regrese al proyecto (mañana , la próxima semana o el próximo mes)

Siéntate, haz 'Ejecutar pruebas' y continúa donde lo dejaste.

Además de los comentarios / listas de tareas / commits, es importante ser realista.

Dependiendo del tamaño, la complejidad y el estado en el que dejó su trabajo, comenzar de nuevo en un proyecto podría llevar un tiempo. Para una base de código sustancial de muchos componentes interactivos, podría llevar días alcanzar la velocidad máxima.

Buena y vieja paciencia será útil.

Cuando me siento abrumado después de regresar a un proyecto después de un tiempo, generalmente tomo la unidad de tarea más simple y más pequeña y la implemento. Me impide perderme tratando de recordar muchas cosas a la vez y aumenta un poco la confianza. En la mayoría de los casos, me encuentro recogiendo automáticamente tareas cada vez más grandes en unas pocas horas.

Llevo un diario del trabajo que hago. Qué hice hoy, qué fue difícil hoy, cuál es el siguiente paso, qué ideas tuve hoy para el futuro. También agrego un poco de narrativa sobre cómo fue el día: ¿hubo una conversación o reunión interesante? ¿Algo enojado o deleitado? Esto ayuda a poner las cosas en perspectiva cuando más tarde leo mi diario.

Cuando vuelvo a un proyecto después de un tiempo, leo las últimas entradas en el diario para ponerme al día con el proyecto. Todos esos pequeños detalles del día a día son increíblemente importantes para recordar el proceso de desarrollo. Realmente marcan una gran diferencia en comparación con una lista de tareas pendientes o la documentación regular del proyecto, ya que le recuerdan cómo fue trabajar en el proyecto y no solo cómo usar el producto.

Para mí, creo que el método más simple para reanudar proyectos es simplemente mantener un registro constante de notas en su trabajo. Encuentro que 'OneNote' de Microsoft es particularmente bueno para mantener y agrupar páginas de notas. En particular, la barra de búsqueda hace que sea extremadamente fácil encontrar rápidamente sus notas en algo.

Aquí hay algunas cosas que hago dentro de OneNote que me ayudan a reanudar el progreso de los proyectos:

• Registros diarios / semanales : mantenga un registro de progreso diario o semanal para ayudarlo a descubrir el progreso que ya ha realizado con un proyecto.

• Lista de tareas pendientes : tengo una lista general de tareas pendientes, pero también mantengo una lista separada de tareas pendientes para los proyectos en los que estoy trabajando, de modo que recuerdo las cosas que todavía tengo que hacer para un proyecto. A veces también dejo // TODO: elementos en mi código.

• Notas del proyecto : las cosas que noto incluyen enlaces a elementos de seguimiento de problemas / proyectos, fragmentos de código, problemas encontrados, decisiones tomadas, planes y descripciones de posibles soluciones, lista de cambios de código, enlaces al directorio del repositorio de código, correos electrónicos para el proyecto y enlaces a documentación del proyecto.

Entonces, cada vez que regreso a un proyecto puedo abrir mis notas y casi instantáneamente puedo ver cuánto progreso se hizo en el proyecto, cuánto trabajo queda por hacer e incluso ver mi tren de pensamiento.

Para proyectos simples, hago esto:

1. Un simple archivo README en el directorio raíz (que, por lo tanto, también terminará en el control de versiones) donde noto lo que aparece durante el desarrollo: cosas que hacer, errores, mejoras / ideas. Ese es el primer archivo que leeré si tengo que poner el proyecto en segundo plano.
2. TODO / FIXME / XXX comentarios
3. A menudo también uso ToDoList