Abandoné mi lugar de trabajo actual ayer, y me encargo de documentar mis proyectos para poder entregárselos fácilmente.Documentación del código al salir de una empresa
Teniendo en cuenta que mi código ya se ha comentado con un buen estándar, ¿qué más debo reunir para ayudar a mis compañeros desarrolladores a hacerse cargo de mis proyectos?
Al trabajar con un nuevo código escrito por otra persona, lo primero que le falta al nuevo chico (o chica) es una descripción general del sistema. Qué subsistemas hay, cuál es su propósito y dónde debe uno mirar para lograr una determinada tarea a mano son algunas preguntas que se le ocurren.
Un documento de inicio conciso, explicando el diseño general del sistema (y las razones por las que se eligió este diseño) tal vez con algunos diagramas, sería algo que estaría muy contento de obtener al trabajar en un software escrito por otra persona .
De acuerdo. Siéntese y piense en lo que necesita cuando se una a su próxima compañía. –
Agrego otra cosa, (otro documento para los errores conocidos y no resuelto) –
¿Entonces, una descripción general y algunas preguntas y respuestas básicas? Las características sin resolver/incompletas son una gran idea para escribir también. – GenericTypeTea
Personalmente escribo todos mis documentos en un estilo descendente, primero dando definiciones a todos los términos (para establecer un vocabulario común) y luego explicando el tema en cuestión en términos generales, refinando detalles más abajo en el documento. Entonces este tipo de documento que cubre todas las partes principales del sistema funcionará muy bien. Además, sería bueno si proporcionó un fundamento para las decisiones arquitectónicas en sus proyectos.
Respecto a la racionalidad para proyectos antiguos ... ¿Cómo explicas las razones detrás de hacer algo hace 18 meses que ahora sabes que está mal ... o más bien no estaba mal en ese momento, pero ahora sabes que no es la mejor manera? – GenericTypeTea
Personalmente escribo todos mis pensamientos en una pequeña wiki "fácil de usar" ... si algo sale mal, solo tengo que buscar en mi wiki ... después solo hablaré con mi colega sobre este tema y lo escribiré abajo en mi documentación. Para mí es importante escribir todo abajo. A veces es un exceso de información, pero funciona para mí. :-) – bastianneu
@GenericTypeTea - En ese caso, puede documentar: 1) por qué se eligió ese diseño en ese momento 2) por qué ahora se considera incorrecto/obsoleto y 3) por qué no se pudo cambiar después del hecho/cómo estabas planeando cambiarlo – samitgaur
Diagramas de secuencia UML para cualquier clase compleja de interacciones de clase/sistema, diagramas de clase para cualquier diseño OO más complejo y diagramas de nivel de sistema que muestran cómo se conectan los diferentes sistemas y aplicaciones.
Puede explicar el diseño del proyecto, cómo funcionan algunas características importantes y quizás pueda documentar las mejoras futuras que haya planificado.
Considere la posibilidad de hacer que su documentación de descripción general de nivel superior sea Wiki: le permite a sus futuros compañeros de trabajo editarla y expandirla fácilmente.
Y un razonamiento (como se mencionó) es muy útil: ¿Por qué eligió la solución A, cuando las soluciones B y C se ven mucho mejor para un observador casual? Puede cortar todo tipo de discusiones interminables de raíz.
Esto puede ser evidente, pero si los proyectos no compilan/ejecutan "fuera de la caja" cuando se registran por primera vez en un entorno de desarrollo nuevo (por supuesto que deberían), un paso por Una guía paso a paso sobre cómo poner todo en marcha salvará a las nuevas personas de muchos dolores de cabeza.
Ojalá no tuviera nada útil que decir aquí, pero como el destinatario del código se transfiere a través de varias caídas, reequilibrios de habilidades, etc., me gustaría repetir y agregar algunos puntos a las respuestas anteriores.
Supongo que su administración ha designado a una o más personas para que se hagan cargo de su trabajo.
Dijiste que no lo necesita de todos modos, pero este no es el momento de agregar comentarios al código.
Ya se señaló que el nuevo propietario del software necesita una descripción general de alto nivel, qué hace el software y qué se necesita para hacerlo. Mantenga este resumen, y trate de no dejar que se desplace en '¿cómo debería ser el software?', No se moleste en rediseñar el sistema desde la tumba.
Luego pase a cuestiones prácticas: quiénes son los interesados, evaluadores y cualquier otra persona que haya participado y pueda conocer este software.
¿Dónde están los requisitos de otra documentación y RP, ¿hay algo especialmente destacable en las relaciones públicas son los próximos requisitos?
Donde en el control de la versión está el sofware, ¿está todo ahí? De Verdad?
¿Qué se necesita para construir el software?
El tiempo más valioso se utilizará para verificar los dos últimos puntos: Recrear un entorno completo de compilación a partir del control de versión y compilación (prueba/entrega) desde la máquina del nuevo propietario. Si hay tiempo, arregle un problema simple.
¡Buena suerte en el nuevo trabajo!
Alguien más ya ha mencionado documentar toda su cadena de herramientas para ayudar a alguien a configurar el entorno de desarrollo. Otra cosa que puede ser demasiado meta es documentar por qué usa esas herramientas.
No hay nada peor que comenzar en un sitio nuevo y planear arrancar todo el MS Word desde la raíz, solo para descubrir cuándo se está codo en el proceso de que la oficina de ventas alemana tenga que generar sus informes TPS en ese formato y no puede usar el JSON de wizbang con el que desea reemplazarlo.
Voy a cerrar esta pregunta como fuera de tema porque no está relacionado con la programación –