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
sequando 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?