Design Document From Code

1

Non ho molta familiarità con la documentazione / progettazione di sistemi.

Devo mantenere un'applicazione scritta in C # - funziona come un servizio Windows.
Tuttavia non esiste documentazione per questo sistema che renda veramente patetico trovare dove si è verificato qualche problema (concettualmente).

Vorrei conoscere il modo migliore per progettare / documentarlo (usando il codice corrente) manualmente o preferibilmente automaticamente in modo da poter identificare i problemi esatti.

Come se mi sentissi come se il diagramma di sequenza non sarebbe di grande aiuto probabilmente.
Inoltre, per favore guidami se lo sto prendendo dalla parte sbagliata?

    
posta UmerK 22.12.2011 - 07:48
fonte

4 risposte

1

Hai test appropriati (inclusi, ma non solo, test unitari) per il sistema? Sembra che tu non lo faccia, nel qual caso vorrei iniziare aggiungendo test sufficienti per assicurarti che l'applicazione si comporti come previsto (poiché non soddisfa i requisiti per il momento, se capisco bene la tua domanda).

Quindi lo scopo della documentazione è di introdurre il codice al nuovo sviluppatore che non sa nulla dell'architettura della base di codice esistente. Significa che la documentazione non è in realtà destinata a trovare dove si è verificato un problema.

Quando il codice si comporta in modo imprevisto, spesso inizi a leggere il codice, non la documentazione vera e propria, che può essere obsoleta o semplicemente totalmente sbagliata o fuorviante . In pratica, quando i sistemi che ho eseguito il debug avevano la documentazione, era obsoleto o sbagliato sempre (relativo al punto di debug). Nessuna eccezione. O la documentazione è stata scritta dai requisiti e l'errore è stato introdotto nel codice, senza riflettere la documentazione, o l'errore è stato la conseguenza di lievi modifiche a livello di codice, mentre la documentazione è rimasta la stessa.

Seguendo i commenti, vedo che ho leggermente frainteso la tua domanda, che è più su "Come ho capito il codebase esistente che non ha alcuna documentazione". Dipende. Nel mio caso, ad esempio, generare diagrammi di classe è qualcosa di prezioso. Questa è la prima cosa che faccio prima di iniziare a lavorare sul codice di qualcun altro, e talvolta l'unica cosa. Ma conosco anche persone che non si preoccupano di generare quei diagrammi, perché lo trovano del tutto inutile.

    
risposta data 22.12.2011 - 08:16
fonte
0

Per la documentazione automatizzata ci sono commenti XML per C # (come javadoc). Tuttavia, ciò rende la documentazione valida solo come i tuoi commenti. Ci sono anche debugger che cercano di visualizzare le cose, ma non le ho trovate così utili.

Per quanto riguarda il documento di progettazione, penso che sia utile avere casi d'uso o storie su come un utente userà un sistema. Questo porta molto bene in BDD (dev del comportamento guidato), che suona come se ti si addice più di cercare di scrivere un lungo piano spec / standardizzato per IEEE.

Tuttavia sembrava che potessi avere alcuni problemi fondamentali. (dal test di Joel :) 1. Usi il controllo del codice sorgente? 4. Hai un database di bug? 7. Hai una specifica? 10. Hai dei tester? Un "no" su una di queste domande ti renderà la vita difficile.

    
risposta data 22.12.2011 - 09:24
fonte
0

Trovo che Doxygen sia molto utile per estrarre informazioni dal codice sorgente grezzo. Metodi, argomenti, tipi, variabili, alberi di dipendenza, alberi di chiamata e chiamanti ... Tutto questo nell'httex ipertestato per saltare tra gli elementi del codice.

Inoltre, se durante le attività di manutenzione inserisci commenti taggati, puoi ottenere quella documentazione sempre più utile.

    
risposta data 22.12.2011 - 09:43
fonte
0

Regole aziendali, modello dati, diagrammi di classe, parametri di configurazione per produzione / test / sviluppo, dettagli di sicurezza in test / dev / produzione, processo di controllo sorgente (dove è l'ultima versione valida!), documentazione del metodo, classi di business e problema i registri (con risoluzione) sono tutte buone informazioni che potrebbero aiutare le persone a gestire un'applicazione. Come hai detto, un diagramma di sequenza non è sufficiente.

    
risposta data 22.12.2011 - 10:54
fonte

Leggi altre domande sui tag