Pensi che il codice sia auto-documentante? [chiuso]

Questa è una domanda che mi è stata posta molti anni fa come laureata in un colloquio di lavoro ed è tormentata nel mio cervello di tanto in tanto e non ho mai trovato una buona risposta che mi soddisfacesse.

L'intervistatore in questione stava cercando una risposta in bianco e nero, non c'era via di mezzo. Non ho mai avuto la possibilità di fare domande sulla logica alla base della domanda, ma sono curioso di sapere perché quella domanda sarebbe stata posta a uno sviluppatore e cosa avresti imparato da una risposta sì o no?

Dal mio punto di vista, posso leggere Java, Python, Delphi ecc., Ma se il mio manager viene da me e mi chiede fino a che punto sono in un progetto e dico "Il codice è completo all'80%" (e prima inizi a spararmi, l'ho sentito pronunciare in un paio di uffici dagli sviluppatori), come si documenta esattamente? Mi scuso se questa domanda sembra strana, ma preferirei chiedere e ottenere alcune opinioni su di essa per ottenere una migliore comprensione del motivo per cui dovrebbe essere posto a qualcuno in un'intervista.

Parzialmente.

Il codice che utilizza Big English Words può essere parzialmente auto-documentato in quanto i nomi di tutte le funzioni e variabili possono dirti cosa sta facendo. Ma probabilmente non ti dirà perché.

Confrontare:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Ma non sai ancora perché è stata avviata un'auto. Quindi, solo parzialmente. È un po 'terribile che il tuo intervistatore si aspettasse una risposta in bianco e nero, a meno che la sua visione del bianco e nero non includesse una forse molto forte.

No. Il codice in sé non è auto-documentante.

Il motivo è che il codice indica COME e non si preoccupa del PERCHÉ, che è ciò che gli umani devono sapere per mantenere il codice.

Quindi hai bisogno di ulteriori commenti che spieghino tutti i PERCHÉ . Puoi limitarli lasciando che i nomi delle tue variabili includano una parte delle decisioni, ma non puoi evitarli.

Il codice corretto ti dice " come ". I commenti giusti ti dicono " perché " .

Pertanto, il codice può auto-documentare il modo in cui le cose vengono realizzate, ma non si può presumere che documenti il ​​motivo.

Se insistono su una risposta in bianco e nero senza una via di mezzo consentita, la risposta è no.

La risposta più completa è che il codice dovrebbe essere auto-documentato nella misura massima ragionevole, ma non esiste un modo ragionevole per includere alcuni tipi di documentazione nel codice. Solo per esempio, il codice potrebbe fare una multa solo per documentare quali informazioni sono raccolte nel modulo A, cosa nel modulo B e cosa nel modulo C. Generalmente non tenterà (e probabilmente non dovrebbe) tentare di documentare i test che dimostrano che la divisione i dati in quel modo hanno ridotto gli errori x% rispetto a (ad esempio) usando solo due moduli anziché tre.

Tutto tranne il pezzo di codice più banale può beneficiare di almeno una documentazione esterna.

La mia risposta. Nella massima misura possibile, dovresti cercare di rendere il tuo codice il più autocompattante possibile. Ci sono molte ragioni per questo. Quando inizialmente scritto, una media di una riga su 10 ha un errore. Gli errori nel codice tendono a essere trovati e risolti. Gli errori nella documentazione tendono ad essere lasciati. E in manutenzione è normale che codice e documentazione si allontanino.

Detto questo, ci sono limitazioni a ciò che può essere fatto rendendo chiaro il codice. In questi casi, è necessario documentare.

Che dire del caso in cui hai la scelta sulla documentazione? La mia opinione è che la manutenzione dipende fortemente dalla tua organizzazione. Se hai eccellenti sviluppatori di software e un rigoroso processo di revisione del codice (come, ad esempio, Google), il tuo processo e le persone possono essere tali da non doverti preoccupare che i commenti non vengano mantenuti. In tal caso, uno stile molto più ricco di commenti ha molto senso. (Google, in effetti, ha uno stile ricco di commenti.) Tuttavia, se hai un'organizzazione più tipica, non mi fiderò molto dei commenti che vedo e spero che tu abbia persone che credevano nel tentativo di rendere il codice auto-documentante. In quella situazione considererò i commenti superflui.

Per un'interessante conversazione sui pregi e gli svantaggi dei commenti, vedere http://www.perlmonks.org/index.pl?node_id=65153 per una vecchia conversazione di cui facevo parte. (Nota, allo stesso tempo abbiamo avuto quella conversazione, c'era una serie privata di chat che era più amichevole. Mi sono sempre pentito che solo la metà più negativa della conversazione sia pubblica.) Le mie opinioni non corrispondono più esattamente a ciò che pensavo allora , ma penso ancora che la conversazione abbia un utile spunto di riflessione.

Trovo che questa domanda sorga molto e spesso abbia un fervore religioso al riguardo. Ecco la mia opinione a riguardo...

In un mondo ideale si potrebbe fare la seguente dichiarazione:

Il codice dovrebbe essere scritto in modo tale che la logica possa essere seguita senza bisogno di commenti.

OK, questo è abbastanza giusto, ma il problema è che non viviamo in un mondo ideale. Ci sono alcuni problemi nel raggiungere questa affermazione ideale.

1. I programmatori spesso non sono gli esperti del settore contro cui stanno programmando. È abbastanza facile capire una funzione come startEngine(Car car)(la maggior parte) tutti possono capire cosa viene chiesto qui. Ma spostati nel mondo reale e le cose diventano un po 'più sfocate. Ad esempio, la funzione getSess(String tid, String aid)sarebbe perfettamente comprensibile per un ingegnere dei trasporti che ha capito i sistemi DWDM, ma può rappresentare una sfida per il nuovo programmatore che ha appena avviato il progetto. I commenti ben inseriti possono aiutare a facilitare la transizione alla comprensione del codice in modo tempestivo.

2. I programmatori che hanno chiesto di mantenere il codice spesso non sono così abili come gli architetti originali del codice. Il programmatore originale potrebbe essere stato abbastanza abile da scrivere un algoritmo rapido, conciso ed efficiente per svolgere un compito specifico. Ma il programmatore incaricato di sostenere che il codice potrebbe avere difficoltà a cercare di capire cosa sta succedendo. I commenti ben inseriti possono aiutare a facilitare la transizione alla comprensione del codice in modo tempestivo.

3. Quante volte hai scritto un po 'di codice, che in seguito hai faticato a capire perché l'hai fatto o anche cosa stavi cercando di ottenere? Lo facciamo tutti di volta in volta. Risolvere un problema e produrre una soluzione facile da seguire a un problema sono spesso due diverse mentalità. A meno che tu non sia la persona in grado di scrivere codice perfettamente fuori dal cancello, spesso fai molti passi falsi con il tuo codice mentre procedi. Potresti anche non essere in grado di tornare a questo bit di codice per un po '. I commenti ben inseriti possono aiutare a facilitare la transizione alla comprensione del codice in modo tempestivo.

4. Situazioni uniche richiedono una spiegazione. Ad esempio un programmatore potrebbe chiedersi perché una pausa di 100ms è stata inserita in un po 'di codice che comunica con un dispositivo DWDM. Consentire al programmatore successivo di sapere che è necessaria una pausa perché il dispositivo è lento nell'assorbimento e potrebbe non avere il comando sarebbe un prezioso pezzo di informazione da avere. I commenti ben inseriti possono aiutare a facilitare la transizione alla comprensione del codice in modo tempestivo.

Il codice ben scritto, "auto-documentante" è una gioia da trovare. Il codice ben scritto, "autocompensante", con commenti informativi ben posizionati è una manna dal cielo e una scoperta molto rara.

Giusto per dare argomenti su ciascun lato della domanda iniziale:

Sì, il codice è auto-documentante. Le variabili, i metodi e i nomi delle classi possono essere tutti resi facili da leggere e da comprendere, in modo che questa sia una forma di auto-documentazione. Potrebbe esserci qualcosa nello stile del codice che fornisce alla fine la documentazione XML considerata procedura standard. In altre parole, fa parte del lavoro dello sviluppatore fornire documentazione che può essere mescolata con il codice.

No, il codice non è auto-documentante. Le decisioni aziendali prese, le scelte di progettazione fatte e altri fattori non appariranno nelle righe di codice e dovrebbero essere scritte al di fuori della base di codice. Pertanto è necessaria la documentazione esterna e questi ne sono esempi.

Punto di domanda: daresti una risposta parziale riconoscendo i limiti di una risposta o ti appoggeresti ciecamente a qualsiasi parte che ritieni sia la pratica migliore? Quanta convinzione hai nella tua risposta se si tratta di un sì o no? Potrebbe essere vista come una domanda stressante progettata per far emergere qualcuno che potrebbe rispondere: "Qual è il ...? Questa è la domanda più stupida che tu possa mai farmi. Mi rifiuto di rispondere sulla base del fatto che insulta la mia intelligenza oltre ogni immaginazione! " come una risposta piuttosto arrogante e pomposa che potrei immaginare alcune persone dare una risposta con quel tono.

Ovviamente era un programmatore letterato nello stile di Knuth. Per un discepolo di LP il codice deve essere auto-documentato per essere valido. Quindi l'unica risposta possibile è "sì".

Il problema qui è che non ci sono molti linguaggi di programmazione alfabetizzati e nessuno di cui io conosca un uso commerciale diffuso. Quindi dovrebbe essere una posizione di nicchia da qualche parte.

Credo che l'intervistatore avrebbe potuto cercare: "Come si scrive il codice di auto-documentazione?" con un implicito "Qual è il tuo atteggiamento nei confronti della documentazione?"

Una volta sono andato a una conferenza davvero ispiratrice di un ragazzo di nome Robert C Martin, dove ha parlato del capitolo "Metodi di scrittura" del suo libro Clean Code.

Stava ovviamente presentando un po 'la posizione di un purista, ma ho accettato il suo consiglio che quando tagli il codice in piccoli metodi riutilizzabili e usi trucchi semplici come:

• Mantenere tutte le dichiarazioni all'interno di un metodo allo stesso livello di astrazione
• Estrarre il contenuto della condizione del flusso di controllo o i blocchi di loop nelle chiamate al metodo
• Quando ti ritrovi a passare gli stessi parametri in diversi metodi in una classe, separando una nuova classe
• E semplici trucchi come la sostituzione di espressioni booleane criptiche con chiamate di metodo
• eccetera...

Si finisce con un codice leggibile, in qualche modo auto-documentante (fintanto che si mette uno sforzo in nomi concisi, ma descrittivi) che è più facile da capire e mantenere.

Ho trovato queste cose davvero utili, ma richiede una conoscenza dei modelli di progettazione per fare bene e devi assolutamente integrare l'approccio con documentazione di classe e metodo di alto livello.

Di solito il codice auto-documentato si riferisce alla pratica dell'uso di una convenzione di denominazione per variabili, funzioni, ecc. Tale che lo scopo del codice è evidente. Quindi, nessun codice da solo non è auto-documentante. Non capisco a cosa ti riferisci nel terzo paragrafo. Questo sembra non avere nulla a che fare con il codice di auto-documentazione.

Jack Reeves ha argomentato in modo convincente che il codice è design . Per quanto riguarda molti, il codice attuale è l'unico "documento" che ti dice cosa fa il sistema. Tutto il resto decade quando un sistema attivo tende a spostarsi sempre più lontano dal sistema progettato. Anche se dovessi generare un documento dal codice (come molti strumenti UML possono fare al giorno d'oggi), è comunque solo una documentazione accurata del sistema in quel momento .

Quindi sì, il codice è auto-documentante. Quanto bene è documentata è un'altra domanda del tutto.

Man mano che sono diventato più esperto, ho imparato che la vera risposta è che il codice più l'ambiente del lettore determina il livello di autocertificazione.

Al fine di ridurre al minimo la varianza tra l'ambiente del lettore e l'ambiente dello scrittore, aggiungiamo commenti. Più commenti sono necessari, in genere meno esperto è lo scrittore. Esiste un saggio davvero meraviglioso che descrive questo aspetto dello sviluppo del software, ma non ricordo chi l'abbia scritto o dove l'ho trovato.

So che la risposta che molte persone si aspettano da questa domanda sarebbe "no", ma ho intenzione di dire di sì. Se me lo chiedessero in un'intervista per un lavoro, direi ancora di sì.

Ho lavorato a molti progetti diversi con open e closed source. Hanno variato la documentazione da semplici commenti lasciati come note del programmatore a documentazioni API complete. Sebbene la documentazione dell'API possa essere eccezionale, alla fine ho sempre raggiunto una situazione in cui la documentazione in lingua scritta era insufficiente per determinare il comportamento effettivo del codice. Ho finito per esaminare il codice sorgente, decodificare le applicazioni o infastidire gli sviluppatori con accesso al codice sorgente per esaminare il codice sorgente e specificare ulteriormente.

Per me, il codice è la documentazione definitiva. Non importa quanto scrivi a parole cosa farà un programma, il comportamento esatto è definito dal codice.

Concordo sul fatto che quando scrivi il codice dovresti provare a rendere il tuo codice il più possibile descrittivo. Tuttavia, come altri hanno già detto, è quasi impossibile in un programma complesso descrivere completamente tutto ciò che il codice sta facendo. Non sono contrario ai commenti, infatti trovo che con buoni commenti possa essere più semplice leggere il codice, anche se il codice potrebbe spiegarsi senza commenti che leggono l'inglese o una lingua parlata è quasi sempre più facile.

Ho scoperto che la documentazione più utile non è quasi mai commenti. La maggior parte dei progetti a cui ho lavorato di recente hanno incluso wiki che includono tutte le diverse parti, come si collegano. Cerco di spiegare cosa avevo in mente quando stavo scrivendo il codice in modo che altre persone non lo spezzassero perché non capivano il perché. Può anche aiutare qualcun altro a riformattare il codice con maggiore sicurezza. Mi trovo spesso titubante al refactoring perché non so mai cosa potrebbe rompersi e non ci sono spiegazioni. Anche se sei l'unica persona che lavora a un progetto che garantisco tra un anno o due dimenticherai perché hai fatto qualcosa, anche se è il codice più bello che puoi ancora dimenticare perché è lì.

Certo, se hai tempo illimitato. Ho trascorso più di 25 anni a documentare il codice per altri sviluppatori. La mia posizione è sempre stata quella di provare a spiegare qualcosa in modo che un altro sviluppatore potesse farlo in 5 minuti, quando potevano semplicemente esaminare il codice e capirlo in mezz'ora. Se salvo tutti coloro che osservano quel metodo per 25 minuti, ho fatto il mio lavoro.

Penso che il diagramma di classe debba sempre essere usato per documentare il codice. Non penso che se guardi direttamente il codice puoi vedere l'architettura completa. Sono d'accordo che se hai scritto il codice da solo o ci lavori da molto tempo, puoi capire ma ogni volta che sorge una nuova richiesta ogni volta che devi guardare il codice e cercare dove aggiungere questo nuovo codice.

Quello che facciamo nella nostra azienda è avere viste dei diagrammi di classe del nostro progetto. Non passiamo molto tempo a modellare, ma utilizziamo solo il diagramma di classe per visualizzare il codice dopo un reverse engineering. Se il codice cambia, allora c'è un meccanismo di unione e i miei diagrammi di classe vengono sempre aggiornati.

Ciò che è fantastico è poter aggiungere commenti, vincoli nel diagramma oltre a java doc. Invertiamo il progetto, quindi creiamo un modello ed estraiamo infine le viste dal modello visualizzate come diagrammi di classe UML. In questa fase non codifico, ma ottengo una stampa blu dall'architettura del codice e ci lavoro per creare o estendere la mia architettura attuale. Se mi piace, premo un pulsante e il mio codice esistente si fonde con i miei diagrammi. Intendo la fusione e certamente non la generazione completa del codice. Viene scritto solo il delta tra il codice esistente e i miei diagrammi, non il codice completo ogni volta.

Ho studiato per molti anni, ho un master e ancora un codice, ma non voglio solo essere uno scrittore di Java e vorrei usare il mio cervello un po 'di più. Le viste UML mi offrono ciò di cui ho bisogno per pensare alla mia architettura, comunicare con gli altri membri del team e creare un'architettura migliore senza utilizzare lo sviluppo guidato dal modello, ma solo il delta tra il codice scritto manualmente esistente e la creazione grafica di diagrammi di classe. Creo la mia architettura a livello di codice, quindi la inverto e guardo il modello. Creo viste e provo a migliorare la mia architettura direttamente nel codice, quindi invertirò di nuovo e vedremo cosa viene fatto ecc. È un'iterazione permanente senza generazione di codice basata su modelli ma sincronizzazione live o unione tra codice e UML. Quello che mi piace è che il codice guida l'UML e certamente non il contrario.