Quale documento dovrebbe descrivere l'utilizzo di una libreria di terze parti in un progetto?

1

Un cliente del mio datore di lavoro ha recentemente richiesto nuove funzionalità per alcuni codici legacy, e poiché gli autori del programma non sono più qui, mi è stato assegnato l'incarico di implementare le nuove funzionalità.

Mi sono stati forniti alcuni documenti di alto livello che risalgono principalmente alle prime fasi del progetto: definizione del progetto, procedure di test black-box, analisi della ricerca della fase iniziale del progetto e così via - niente a un livello tecnico.

Il codice fa ampio uso di una libreria di terze parti ( Lemur Indri ) per l'indicizzazione e il recupero di materiali indicizzati, ma non c'è documentazione su come usiamo questa libreria, o perché è stata scelta. Ho passato molto tempo a studiare la biblioteca stessa e il modo in cui la usiamo; Mi sento come se fosse tempo sprecato.

Durante un incontro con il mio supervisore ho detto che sarebbe stato bello se gli sviluppatori del nostro sistema avessero scritto della documentazione sulla libreria e su come la usassimo. Gli ho detto che mi avrebbe risparmiato un sacco di tempo, ma non potevo convincerlo che questo tipo di cose è essenziale.

Penso che scrivere una simile documentazione aiuti i futuri sviluppatori a prendere confidenza con il sistema e ad eseguire le modifiche più velocemente. Se dovesse esserci un tale documento, come si chiamerebbe o dovrebbe essere incluso in uno dei documenti di progettazione?

    
posta mrz 11.06.2013 - 11:57
fonte

3 risposte

3

Il posto giusto per questo tipo di documentazione è nel codice stesso. Nota a margine, la documentazione è notoriamente inaccurata, quindi la soluzione migliore, come sviluppatore, è creare il codice più chiaro e conciso possibile.

Idealmente, la libreria di terze parti è isolata in una singola Classe o Modulo in modo che possa essere facilmente compresa e documentata. Se la libreria penetra nel dominio potrebbero esserci anche dei problemi di accoppiamento di cui devi preoccuparti.

    
risposta data 11.06.2013 - 14:46
fonte
2

Tutto il codice dovrebbe includere la documentazione / i commenti necessari per renderlo chiaro.

Questo include la documentazione su come e perché è stata usata una libreria. Non è necessario ripetere la documentazione per la libreria, ma se non è possibile comprendere l'uso del codice della libreria senza ore di documentazione, è necessario includere alcune informazioni su come viene utilizzato.

Il posto per questo è la documentazione di base per il codice; non dovrebbe essere separato semplicemente perché si tratta di una libreria.

    
risposta data 11.06.2013 - 14:26
fonte
1

Tutte le risposte di cui sopra vanno bene. Un elemento mancante, però, è l'informazione necessaria per tracciare (almeno) aggiornamenti di sicurezza e correzioni di errori nella libreria:

  • Eventuali informazioni di contatto (mailing list e siti Web).
  • Limiti di fine vita (se presenti)
  • Istruzioni specifiche sulla convalida dei risultati e delle prestazioni della libreria nel tuo ambiente dopo un aggiornamento a monte (i risultati numerici potrebbero cambiare a causa di regressioni o correzioni di bug / prestazioni - devi sapere quali casi di test aggiornare e quali dovrebbero rimanere gli stessi) .
risposta data 17.06.2013 - 18:40
fonte

Leggi altre domande sui tag