come documentare i risultati della programmazione per i non programmatori

3

Continuo a imbattersi in un problema sul lavoro, e spero che gli altri sappiano una soluzione sia dall'esperienza personale che dalle migliori pratiche.

Non sono un programmatore. Io, comunque, uso pesantemente le tabelle RDBMS che sono popolate dal codice scritto dai nostri programmatori. Uso anche altri prodotti dei nostri sviluppatori '. Molto spesso, questi prodotti non sono documentati.

Ecco un esempio (generico): abbiamo una tabella che indica le modifiche di stato agli account. Pensavo che fosse incluso ogni volta che qualcuno tenta il cambiamento; risulta, include solo modifiche riuscite ed esclude i tentativi di passare allo stato attualmente detenuto. Questo influenza notevolmente le mie domande su quel tavolo. Ma nessuno lo ha mai documentato da nessuna parte.

Un altro esempio: una richiesta di funzionalità JIRA ha richiesto che alcuni cron abbiano effetto sugli account dopo n giorni di inattività dei conti. Ciò significa esattamente 24 ore n ? Significa che la differenza di date tra l'ultima attività e il cron dovrebbe essere n ? Qualcos'altro, forse? Di nuovo, la definizione precisa qui influenza le mie query sulla tabella pertinente, ma non è documentata.

In entrambi i casi, ho dovuto sedermi con lo sviluppatore pertinente, che ha letto un sacco di codice, alcuni dei quali lei stessa aveva scritto, per determinare cosa il codice faceva. Questa è una perdita di tempo per lo sviluppatore, che dovrà sedersi con un altro dipendente qualche mese dopo quando lui / lei ha la stessa domanda e il programmatore non ricorda la risposta. E poi ancora qualche mese più tardi.

Cosa dovremmo fare a riguardo? Sembra che ci sia una sorta di documentazione necessaria. Dove dovrebbe essere? O la situazione attuale è ideale?

Alcune idee a cui ho pensato:

  • Commenta tabelle e colonne RDBMS. (Il RDBMS che usiamo consente questo.) O disporre di una documentazione separata suddivisa per tabella RDBMS. Ma uno sviluppatore qui correttamente mi ha detto che se quando uno sviluppatore non riesce a documentare qualcosa, la gente si affiderà a una documentazione obsoleta, che è peggio di la situazione attuale. Inoltre, questo dovrebbe solo documentare l'RDBMS; ci sono, naturalmente, altri prodotti degli sviluppatori.
  • In qualsiasi problema JIRA (la maggior parte, forse la totalità, delle nostre modifiche al codice sono in JIRA), includere il nome della tabella RDBMS (e / o altri termini di ricerca importanti) e la documentazione di ciò che è stato fatto. In questo modo, le persone che desiderano conoscere il prodotto di qualsiasi sviluppatore hanno una posizione centrale per la ricerca e possono leggere la documentazione di ogni diff.

Qualcuno ha una soluzione? Cosa fanno le altre aziende? Che cosa hai visto o quali sono le migliori pratiche?

    
posta msh210 21.12.2017 - 19:00
fonte

2 risposte

5

In generale, la documentazione più vicina è al codice che documenta, più è probabile che rimanga corretta nel tempo. Questo è uno dei motivi per cui la documentazione di riferimento generata automaticamente come Javadoc e Doxygen funziona meglio della documentazione di riferimento scritta esternamente: la sintassi di utilizzo che ha generato la documentazione mostra per definizione sempre corretta (tratta direttamente dal codice), e i commenti sono proprio accanto alle dichiarazioni nel codice, quindi c'è una possibilità che qualcuno modifichi il codice per cambiare l'interfaccia vedrà e (speriamo) aggiorni il commento.

Se il tuo database supporta tabelle e colonne di commenti, verifica se esiste un modo per generare automaticamente la documentazione di riferimento da tali commenti. La documentazione generata è più facile da esplorare e cercare rispetto a ripetere ripetutamente l'equivalente SQL di "man cmd " una tabella o colonna alla volta. (Non ho esperienza con la documentazione di auto-generazione dai commenti nei database, quindi non posso suggerire strumenti. Controlla se la documentazione per la piattaforma di database che stai usando dice qualcosa a riguardo, dove parla di come aggiungere commenti alle tabelle / colonne.)

Solo generare documentazione dai commenti (o accedere ai commenti dalla riga di comando) è improbabile che risolva il tuo intero problema. Lo vediamo anche con le API; la documentazione di riferimento indica come ogni classe, funzione, ecc funziona individualmente, e potrebbe avere qualche documentazione di panoramica aggiunta, ma di solito non fornisce informazioni di livello superiore sull'uso previsto, informazioni concettuali, esempi ben documentati, e così via sopra. Inoltre, hai affermato che devi documentare cose che non sono definizioni di tabelle e colonne.

Pertanto suggerisco un approccio ibrido: generare documentazione di riferimento dai commenti se possibile, e creare un luogo in cui è possibile creare e curare congiuntamente altra documentazione in caso di necessità. Un wiki funziona bene per questo (ed è ricercabile). La documentazione esterna è intrinsecamente meno affidabile di il codice effettivo , quindi avrai bisogno della volontà di crearlo e per tenerlo aggiornato. Funziona meglio in progetti a bassa volatilità; se le tue interfacce cambiano ogni giorno, la documentazione esterna è prematura.

Se è necessario documentare le tabelle esternamente invece di ricavare la documentazione dal codice e dai commenti, un formato che il mio team ha trovato utile è il seguente. Per ogni tabella, scrivi un paragrafo o due su cosa è la tabella e (se pertinente) come si riferisce ad altre tabelle. Se ci sono restrizioni sull'uso (come i privilegi), includi anche quello. Quindi crea una tabella con tre colonne: nome della colonna, tipo di dati, descrizione.

Infine, in assenza di documentazione, a volte trovo le risposte a come qualcosa veramente funziona nel codice di test. (Un commento menziona anche questo.) I tuoi sviluppatori hanno suite di test? I test (comprese le query SQL) e l'output previsto sono accessibili? In tal caso, controlla se trovi le risposte lì se non vuoi disturbare uno sviluppatore, quindi utilizza ciò che hai imparato per migliorare la documentazione interna, ovunque la mantieni.

    
risposta data 21.12.2017 - 20:18
fonte
1

Penso che il problema è che ti aspetti un livello scientifico di funzionalità definite da un prodotto che non è sviluppato per quello standard.

Alcuni programmi sono specificati e sviluppati con tolleranze molto elevate. In questi casi puoi aspettarti che la documentazione dichiari esattamente che cosa fa il programma. Ad esempio compilatori, implementazioni di funzioni matematiche, driver per hardware ecc.

Tuttavia, per la maggior parte delle applicazioni line-of-business le specifiche sono molto più lente e, di conseguenza, la funzionalità non è definita dopo aver eseguito il drill-down di quanto richiesto in origine.

Il tuo esempio JIRA è buono. "L'account deve cambiare dopo n giorni" è una specifica piuttosto specifica se sei un addetto alle vendite o addirittura un assistente. Si irritavano se lo sviluppatore tornava a chiedere informazioni sull'ora legale e sui secondi bisestili.

Se torni più tardi e fai la stessa domanda, la risposta è "indefinita", potrebbe fare x o potrebbe fare y. È uno strumento smussato.

    
risposta data 21.12.2017 - 22:01
fonte

Leggi altre domande sui tag