Mi sono dimesso dal mio attuale posto di lavoro ieri, e mi sto prendendo la responsabilità di documentare i miei progetti in modo da poterli consegnare facilmente.Codice di documentazione al momento di lasciare una società
Tenendo presente che il mio codice è già commentato ad un buon livello, cos'altro dovrei mettere insieme per aiutare i miei colleghi sviluppatori a prendere in consegna i miei progetti?
Quando si lavora con un nuovo codice scritto da qualcun altro, la prima cosa che manca al nuovo ragazzo (o ragazza) è una panoramica del sistema. Quali sottosistemi ci sono, qual è il loro scopo e dove uno dovrebbe cercare di portare a termine un determinato compito a portata di mano sono alcune domande che vengono in mente.
Un breve documento di partenza, che spiega la struttura generale del sistema (e le ragioni per cui è stato scelto questo disegno), magari con alcuni diagrammi, sarebbe qualcosa che sarei davvero felice di ottenere lavorando su un software scritto da qualcun altro .
concordato. Siediti e pensa a ciò di cui hai bisogno quando ti unisci alla tua prossima compagnia. –
Aggiungo un'altra cosa, (un altro documento per i bug noti e non risolto) –
Quindi, una panoramica generale e alcune domande e risposte di base? Le caratteristiche non risolte/incomplete sono una grande idea da scrivere anche. – GenericTypeTea
Personalmente scrivo tutti i miei documenti in uno stile dall'alto verso il basso, prima dando definizioni a tutti i termini (per stabilire un vocabolario comune) e poi spiegando il soggetto in questione in termini generali, perfezionando i dettagli più in basso nel documento. Quindi questo tipo di documento che copre tutte le parti principali del sistema farà abbastanza bene. Inoltre, sarebbe bello se fornissi una motivazione per le decisioni architettoniche nei tuoi progetti.
Riguardo alla razionalità per i vecchi progetti ... Come spieghi le ragioni che stanno dietro a fare qualcosa 18 mesi fa che ora sai essere sbagliato ... o meglio non era sbagliato in quel momento, ma ora sai che non è il modo migliore? – GenericTypeTea
Personalmente scrivo tutti i miei pensieri in un piccolo Wiki "facile da usare" ... se qualcosa si rivela sbagliato, devo solo cercare nella mia wiki ... dopodiché devo solo parlare con il mio collega di questo problema e scriverlo giù nella mia documentazione. Per me è importante scrivere tutto. A volte è un eccesso di informazioni, ma funziona per me. :-) – bastianneu
@GenericTypeTea - In questo caso puoi documentare - 1) perché quel design è stato scelto in quel momento 2) perché ora è considerato sbagliato/obsoleto e 3) perché non può essere cambiato dopo il fatto/come stavi progettando di cambiarlo. – samitgaur
Diagrammi di sequenza UML per qualsiasi interazione complessa di classe/sistema, diagrammi di classe per eventuali progetti OO più complessi e diagrammi a livello di sistema che mostrano come diversi sistemi e app si connettono tra loro.
Puoi spiegare il design del progetto, come funzionano alcune funzioni importanti e forse puoi documentare eventuali miglioramenti futuri che hai pianificato.
Considera di rendere la documentazione panoramica di primo livello un Wiki - consente ai tuoi futuri ex colleghi di modificarlo ed espanderlo facilmente.
E una motivazione (come accennato) è molto utile: perché hai scelto la soluzione A, quando le soluzioni B e C sembrano molto meglio per un osservatore casuale? Può stroncare sul nascere infinite discussioni senza fine.
Questo potrebbe essere evidente, ma se i progetti non vengono compilati/eseguiti "out of the box" al momento del check-out per la prima volta in un nuovo ambiente di sviluppo (ovviamente dovrebbero), un passaggio Una guida completa su come ottenere tutto funzionante salverà le nuove persone da un sacco di mal di testa.
Mi piacerebbe non avere nulla di utile da dire qui, ma poiché il destinatario del codice si trasferisce attraverso diverse recessioni, riorganizzazioni di abilità ecc., Vorrei ripetere e aggiungere alcuni punti alle risposte precedenti.
Presumo che la tua direzione abbia nominato una o più persone a subentrare nel tuo lavoro.
Hai detto che non ne hai comunque bisogno, ma non è il momento di aggiungere commenti al codice.
È stato già sottolineato che il nuovo proprietario del software richiede una panoramica di alto livello, cosa fa il software e cosa è necessario per farlo. Tieni questo breve, e cerca di non lasciare che diventi in "come dovrebbe essere il software", non preoccuparti di re-architettare il sistema dalla tomba.
Quindi passare a questioni pratiche: chi sono gli stakeholder, i tester e chiunque altro è stato e potrebbe essere coinvolto e conoscere questo software.
Dove sono i requisiti altra documentazione e PR, c'è qualcosa di particolarmente degno di nota nelle PR sono i prossimi requisiti?
Dove nel controllo della versione è presente il software, c'è tutto? Veramente?
Cosa è necessario per creare il sofware?
Il tempo più prezioso sarà dedicato alla verifica degli ultimi due punti: Ricreare un ambiente di compilazione completo dal controllo di versione e generazione (prova/consegna) dal nuovo computer del proprietario. Se c'è tempo, risolvi un problema semplice.
Buona fortuna nel nuovo lavoro!
Qualcun altro ha già menzionato la documentazione dell'intera toolchain per aiutare qualcuno a configurare l'ambiente di sviluppo. Un'altra cosa che potrebbe essere un po 'troppo meta è quella di documentare perché si utilizzano quegli strumenti.
Non c'è niente di peggio che iniziare da qualche parte nuovo e progettare di strappare tutto il MS Word dalle radici, solo per scoprire quando sei gomito nel processo che l'ufficio vendite tedesco deve avere i loro rapporti TPS generati in quel formato e non è possibile utilizzare il JSON wizbang con il quale si desidera sostituirlo.
Sto votando per chiudere questa domanda come off-topic perché non è correlato alla programmazione –