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

parzialmente.

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

Confronto:

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é si sta avviando un'auto. Quindi, solo parzialmente. È un po 'terribile che il tuo intervistatore si aspettasse una risposta in bianco e nero, a meno che il suo punto di vista del bianco e nero includesse un messaggio molto strong.

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

Il motivo è che il codice dichiara HOW e non si preoccupa di WHY che è ciò che gli umani devono sapere per mantenere il codice.

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

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

Quindi il codice può essere auto-documentante nel modo in cui le cose vengono raggiunte, ma non puoi presumere che documenti la ragione per cui.

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

La risposta più completa è che il codice dovrebbe essere auto-documentante nella misura massima ragionevole, ma non c'è un modo ragionevole per includere alcuni tipi di documentazione nel codice. Per esempio, il codice potrebbe fare una multa solo per documentare quali informazioni sono raccolte sul modulo A, cosa in forma B e cosa su modulo C. In genere non tenterà (e probabilmente non dovrebbe) di documentare i test che mostrano quella divisione i dati su in questo modo riducevano gli errori x% rispetto a (per esempio) usando solo due moduli invece di tre.

Qualunque cosa, tranne la parte più banale del codice, può trarre beneficio almeno da una documentazione esterna.

La mia risposta. Nella massima misura possibile, dovresti cercare di rendere il tuo codice più auto-documentabile 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 a essere lasciati. E in manutenzione è comune che codice e documentazione si allontanino.

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

E il caso in cui hai la possibilità di documentare? La mia opinione è che la manutenzione dipende strongmente dalla tua organizzazione. Se disponi di eccellenti sviluppatori software e di un rigoroso processo di revisione del codice (come, ad esempio, Google), i tuoi processi e le persone possono essere tali da non dover essere preoccupati per i commenti che non vengono mantenuti. In questo caso, uno stile molto più commentato ha molto senso. (Google, in effetti, ha uno stile pesante per i commenti.) Tuttavia, se hai un'organizzazione più tipica, ho intenzione di diffidare pesantemente dei commenti che vedo, e spero che tu abbia persone che credono nel tentativo di rendere il codice auto-documentante. In quella situazione considererò i commenti superflui.

Per un'interessante conversazione sui vantaggi e gli svantaggi dei commenti, vedi link per una vecchia conversazione I era parte di (Nota, allo stesso tempo abbiamo avuto quella conversazione, c'era una serie privata di chat che erano più amichevoli.Mi sono sempre pentito che solo la metà più negativa della conversazione è pubblica.) Le mie opinioni non corrispondono più esattamente a quello che pensavo allora , ma continuo a pensare che la conversazione abbia un utile spunto di riflessione.

Trovo che questa domanda sembri molto e spesso ha un fervore religioso a riguardo. Ecco la mia opinione su questo ...

In un mondo ideale potrebbe essere fatta la seguente dichiarazione:

Code should be written in such a way, that the logic can be followed without needing commenting.

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

1. I programmatori spesso non sono gli esperti del settore a 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ù confuse. Ad esempio la funzione getSess(String tid, String aid) sarebbe perfettamente comprensibile per un ingegnere del trasporto che capisse i sistemi DWDM, ma potrebbe presentare una sfida al nuovo programmatore appena messo sul progetto. I commenti ben posizionati possono facilitare il passaggio alla comprensione del codice in modo tempestivo.

2. I programmatori che hanno richiesto di mantenere il codice spesso non sono esperti quanto gli architetti originali del codice. Il programmatore originale potrebbe essere stato abbastanza esperto da scrivere un algoritmo veloce, sintetico ed efficiente per eseguire un compito specifico. Ma il programmatore con il compito di mantenere quel codice potrebbe faticare a cercare di capire cosa sta succedendo. I commenti ben posizionati possono facilitare il passaggio alla comprensione del codice in modo tempestivo.

3. Quante volte hai scritto un po 'di codice, che in seguito hai faticato a capire perché lo hai fatto, o anche cosa stavi cercando di ottenere? Lo facciamo tutti di tanto in tanto. 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 che può scrivere codice perfettamente fuori dal cancello, spesso fai molti passi falsi con il tuo codice mentre vai avanti. Potrebbe anche non essere in grado di tornare a questo bit di codice per un po '. I commenti ben posizionati possono facilitare il passaggio alla comprensione del codice in modo tempestivo.

4. Le situazioni uniche richiedono spiegazioni. Ad esempio un programmatore potrebbe chiedersi perché una pausa di 100 ms è stata inserita in un bit di codice che comunica con un dispositivo DWDM. Lasciando che il programmatore successivo sappia che è necessaria una pausa perché il dispositivo è lento nell'assorbimento e potrebbe mancare il comando sarebbe un prezioso bit di informazione da avere. I commenti ben posizionati possono facilitare il passaggio alla comprensione del codice in modo tempestivo.

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

Solo 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 fatti per essere facili da leggere e capire in modo che questa sia una forma di auto-documentazione. Potrebbe esserci qualcosa all'interno dello stile del codice che fornisce documentazione XML alla fine che è considerata una procedura standard. In altre parole, fa parte del lavoro dello sviluppatore fornire documentazione che possa essere mescolata con il codice.

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

Punto di domanda: daresti una risposta parziale riconoscendo i limiti di una risposta o ti appoggeresti ciecamente a qualsiasi parte tu ritenga sia la migliore pratica? Quanta convinzione hai nella tua risposta se si tratta di un sì o di un no? Potrebbe essere vista come una domanda stressante progettata per suscitare l'ascesa di qualcuno che potrebbe rispondere: "Che cosa ...? Questa è la domanda più stupida che tu possa mai chiedermi." Mi rifiuto di rispondere affermando che insulta la mia intelligenza è incredibile! " come una risposta piuttosto arrogante e pomposa che potrei immaginare alcune persone che danno una risposta con quel tono.

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

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

Penso che quello che l'intervistatore potrebbe aver cercato è: "Come scrivi codice di auto-documentazione?" con un implicito "Qual è il tuo atteggiamento nei confronti della documentazione?"

Sono andato a una conferenza davvero ispirata da un ragazzo di nome Robert C Martin, una volta in cui ha parlato del capitolo "metodi di scrittura" del suo libro Clean Code.

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

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

Finisci con un codice leggibile e un po 'auto-documentante (a patto che tu ti impegni in nomi concisi ma descrittivi) che è più facile da capire e da mantenere.

Ho trovato questa roba davvero utile, ma richiede una conoscenza dei modelli di progettazione per fare bene e devi assolutamente integrare l'approccio con la documentazione dei metodi di classe e di alto livello.

Di solito il codice di auto-documentazione si riferisce alla pratica di utilizzare una convenzione di denominazione per variabili, funzioni, ecc. in modo tale che lo scopo del codice sia evidente. Quindi, nessun codice di per sé non è auto-documentante. Non capisco a cosa ti riferisci nel terzo paragrafo. Ciò 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 vero codice è l'unico "documento" che ti dice cosa fa il sistema. Tutto il resto decade come un sistema live tende a spostarsi sempre più lontano dal sistema progettato. Anche se dovessi generare un documento dal codice (come molti strumenti UML possono fare oggigiorno), è ancora solo una accurata documentazione del sistema in quel momento .

Quindi sì il codice è auto-documentante. Quanto bene è documentato è un'altra domanda alltogether.

Come ho acquisito maggiore esperienza, ho appreso che la vera risposta è che il codice e l'ambiente del lettore determinano il livello di autodocumentazione.

Per ridurre al minimo la varianza tra l'ambiente del lettore e l'ambiente dello scrittore, aggiungiamo commenti. Più commenti sono necessari, in genere meno esperti dello scrittore. C'è un saggio davvero meraviglioso là fuori che descrive questo aspetto dello sviluppo del software, ma non ricordo chi l'ha scritto o dove l'ho trovato.

Conosco la risposta che la maggior parte delle persone si aspetta che quella domanda sia "no", ma dirò di sì. Se mi venisse chiesto questo in un'intervista per un lavoro, direi di sì.

Ho lavorato su molti progetti diversi con open source e closed source. Hanno spaziato nella documentazione da semplici commenti lasciati come note del programmatore alle documentazioni API complete. Sebbene la documentazione dell'API possa essere eccezionale, ho sempre raggiunto una situazione in cui la documentazione in linguaggio scritto non era sufficiente per determinare il comportamento effettivo del codice. Ho finito con l'esaminare il codice sorgente, l'ingegneria inversa delle applicazioni o il pesting degli sviluppatori con accesso all'origine per esaminare il codice sorgente e specificare ulteriormente.

Per me, il codice è la documentazione definitiva. Indipendentemente da quanto scrivi a parole ciò che un programma sta per fare, il comportamento esatto è definito dal codice.

Sono d'accordo che quando si scrive codice si dovrebbe cercare di rendere il proprio codice il più descrittivo possibile. Tuttavia, come altri hanno già detto, è quasi impossibile in un programma complesso descrivere completamente tutto ciò che sta facendo il codice. Non sono contrario ai commenti, infatti trovo che con buoni commenti possa essere più facile leggere il codice, anche se il codice potrebbe spiegarsi da solo senza i commenti che leggono in inglese o una lingua parlata è quasi sempre più semplice.

Ho scoperto che la documentazione più utile non è quasi mai commenti. La maggior parte dei progetti a cui ho lavorato di recente ha incluso un wiki che include tutte le diverse parti, come si connettono. Cerco di spiegare cosa avevo in mente quando stavo scrivendo il codice in modo che altre persone non violassero il mio codice perché non ne capivano il perché. Può anche aiutare qualcun altro a ridefinire il codice con maggiore sicurezza. Spesso mi trovo esitante nel codice refactoring perché non so mai cosa potrebbe rompere e non c'è spiegazione. Anche se sei l'unica persona che lavora su un progetto che garantisco tra un anno o due, dimenticherai perché hai fatto qualcosa anche se è il pezzo di codice più bello che puoi ancora scordare perché è lì.

Certo, se hai tempo illimitato. Ho trascorso oltre 25 anni a documentare il codice per altri sviluppatori. La mia posizione è sempre stata che cerco di spiegare qualcosa in modo che un altro sviluppatore possa eliminarlo in 5 minuti, quando potrebbero semplicemente esaminare il codice e capirlo in una mezz'ora. Se salvo tutti quelli che osservano quel metodo per 25 minuti, ho fatto il mio lavoro.

Penso che il diagramma delle classi dovrebbe sempre essere usato per documentare il codice. Non penso che se guardi direttamente il codice puoi vedere l'architettura completa. Sono d'accordo sul fatto che se hai scritto il codice da solo o ci hai lavorato per lungo tempo, puoi capire ma ogni volta che si presenta una nuova richiesta ogni volta che devi consultare il codice e cercare dove aggiungere questo nuovo codice.

Ciò che facciamo nella nostra azienda è di avere una visione dei diagrammi di classe del nostro progetto. Non passiamo molto alla modellazione del tempo, ma usiamo solo il diagramma delle classi per visualizzare il codice dopo un reverse engineering. Se il codice cambia, esiste un meccanismo di unione e i miei diagrammi delle classi vengono sempre aggiornati.

Ciò che è fantastico è poter aggiungere commenti, vincoli nel diagramma oltre a java doc. Invertiamo il progetto, quindi creiamo un modello ed infine estraiamo le viste dal modello visualizzato come diagrammi delle classi UML. In questo momento non codifico ma ottengo una stampa blu dall'architettura del codice e lavoro su di essa per creare o estendere la mia architettura corrente. Se mi piace, premo un pulsante e il mio codice esistente si unisce ai miei diagrammi. Intendo fusione e certamente non completa generazione di codice. Solo il delta tra il codice esistente e i miei diagrammi viene scritto, non il codice completo ogni volta.

Ho studiato per molti anni, ho una laurea e codice, ma non voglio essere solo una scrittrice di java e vorrei usare il mio cervello un po 'di più. Le visualizzazioni UML mi forniscono 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 di Model Driven ma solo il delta tra codice scritto manualmente e creato graficamente diagrammi di classe. Creo la mia architettura a livello di codice, quindi la inverto e guardo il modello. Creo le viste e cerco di migliorare la mia architettura direttamente nel codice, quindi di tornare indietro e vedere cosa viene fatto ecc ... È una iterazione permanente senza generazione di codice basata su modelli, ma sincronizzazione o unione tra codice e UML. Quello che mi piace è che il codice guida l'UML e certamente non il contrario. Il diagramma delle classi UML è per me un abbellitore del mio codice e mi piace !!