buona sostituzione per commentare il codice? [duplicare]

30

Mi dà fastidio vedere il codice commentato e sembra spesso, a volte un sintomo di sviluppatori che non sono abili nelle funzioni avanzate di controllo del codice sorgente, ma d'altra parte il controllo del codice sorgente non risolve completamente il problema che commenta fuori è destinato per. Di tanto in tanto ho visto i requisiti flip-flop in modo tale che il codice che sarebbe stato cancellato improvvisamente è di nuovo necessario. Se il codice è veramente cancellato, non sembra esserci una procedura chiara per localizzare esattamente dove trovare quel codice cancellato nel controllo del codice sorgente.

Esiste un modo migliore per salvare il lavoro degli sviluppatori che potrebbe essere necessario di nuovo oltre al "commento" provato e vero?

    
posta JoelFan 07.10.2013 - 23:41
fonte

8 risposte

20

Siamo abbastanza rigorosi su questo, e la linea guida è che il codice commentato non dovrebbe essere archiviato. La logica alla base di questo è che non si può mai veramente sapere se l'ingegnere ha dimenticato di decommentarlo prima di verificarlo. Anche con un commento che spiega perché il codice è commentato, c'è ancora un elemento di dubbio. Se ne hai bisogno, puoi recuperarlo dal controllo del codice sorgente.

A mio avviso, il pericolo di cambiare i requisiti è inferiore al pericolo (e alla probabile incertezza) di vedere un blocco di codice commentato (in particolare in un futuro lontano) e chiedersi se dovrebbe esserci o no no.

Alla fine della giornata, anche con le specifiche, le storie degli utenti, i biglietti di Jira e tutto ciò che è jazz, "il codice è la documentazione" - è l'unico riferimento definitivo su cosa effettivamente qualcosa < em> fa .

Ovviamente è solo una linea guida; Sono sicuro che otterrai delle risposte davvero grandi - non vedo l'ora di leggerli!

Sinceramente: non controllare il codice commentato, ma lascia una nota nel tracker del problema. Scrivi nel numero di revisione e nella posizione dell'implementazione alternativa. Il codice rimane pulito e tu aiuti il tuo sé futuro. Se / quando i requisiti cambiano, il ticket di implementazione verrà (dovrebbe) riaperto, e puoi usare il tuo breadcrumb per trovare la versione precedente. Alcuni tracker di problemi tracciano automaticamente la modifica nel controllo del codice sorgente direttamente sul ticket: questo è un altro aiuto per te.

    
risposta data 07.10.2013 - 23:52
fonte
5

Supponendo che il controllo del codice sorgente sia attivo, sarebbe probabilmente più facile mantenere un ramo (o uno shelf / stash) per il codice commentato piuttosto che dover passare attraverso un gruppo di file e annullare / commentare un intero gruppo di codice. Serve anche lo scopo secondario di separare logicamente quel codice dal resto della base di codice che è più stabile.

    
risposta data 07.10.2013 - 23:53
fonte
5

La risposta è cancellarla. La domanda è quindi cosa fare con esso dopo l'eliminazione in modo che si possa trovare di nuovo. Questo dipende in parte dal VCS.

L'eliminazione ha il problema che non è possibile trovare facilmente qualcosa con blame ( git e svn hanno entrambi una funzione per mostrare dove è stato aggiunto qualcosa - e il post sul blog di Coding Horror - Chi ha scritto Questo schifo? ).

Tuttavia, se inserisci un commento al suo posto, viene visualizzato nelle annotazioni e nel codice corrente.

Si potrebbe (ad esempio), sostituire il blocco di codice con

/* code removed here that does frob()
 * no longer needed because of XYZ requirement
 * see f7f6023 for removed code
 */ 

Probabilmente potresti semplificarlo a una riga o qualcosa in modo che non sia proprio il pugno nell'occhio che io abbia. L'idea è di lasciare un 'angolo piegato della pagina' nel codice in modo che qualcuno possa trovarlo di nuovo. Certo, non farlo per il blocco di codice ogni che fai fuori. Se stai solo prendendo una linea piuttosto noiosa, prendila e finiscila. Non c'è bisogno di ingombrare la mente quando legge la fonte (che è lo spot per il messaggio di commit)

Sottolineerò che git ha un leggero vantaggio qui di essere in grado di specificare il checksum del genitore più facilmente di quanto altri VCS possano specificare la posizione del genitore (potrebbe essere in un ramo, potrebbe non esserlo)

Se sei su Github o un repository simile in house, puoi invece estrarlo in un gist e fare riferimento a ciò nel commento .

Se non sei illuminato da un sistema VCS, puoi spostare l'idea di un gist nella propria directory 'snippet' che fa riferimento a pezzi di dimensioni considerevoli di funzionalità che vuoi tenere in giro.

Il metodo di estrazione di gist e snippet ha il vantaggio che si può cercare facilmente all'interno di questo codice. Non dovresti usarlo solo per il codice cancellato, ma piuttosto i modelli su come fare qualcosa. Quel qualcosa è stato cancellato ad un certo punto nel tempo non è un motivo non per salvare lo snippit.

A tal fine, suggerirei anche di guardare la domanda Best practice per condividere minuscoli frammenti di codice in tutti i progetti per idee sui modi migliori per farlo.

Un altro approccio è quello di salvare la patch che hai rimosso il codice in questione nel sistema di tracciamento del problema stesso. Salvando la patch per il codice remove salva anche il codice che è stato rimosso. La ricerca nel sistema di rilevamento dei problemi cercherà anche il codice rimosso.

    
risposta data 08.10.2013 - 02:30
fonte
2

Alcune buone risposte già qui, ma vorrei aggiungere un punto.

I've occasionally seen requirements flip-flop in such a way that code that would have been deleted suddenly is needed again.

Questo è il punto su cui dovresti lavorare: meglio identificare i requisiti e il motivo perché cambiano. Se cambiano perché la prima analisi non era corretta, o il tuo cliente aveva bisogno di alcuni prototipi fino a che non capiva cosa voleva veramente, le probabilità che si stabilizzassero dopo alcune iterazioni sono alte. Quindi diventa ovvio che puoi cancellare il vecchio codice e mantenere solo il codice che fa quello che dovrebbe.

Se, tuttavia, le tue esigenze cambiano a causa della sua parte di attività (ad esempio, il requisito A è per gennaio, marzo e giugno e B per febbraio, aprile e luglio), potrebbe essere probabilmente errato supportare solo Un'implementazione - in tal caso, l'applicazione potrebbe supportare meglio quei diversi requisiti contemporaneamente, supportandoli in modo generalizzato o consentendo alcune personalizzazioni o configurazioni. In tal caso, tutto il codice rimane nell'applicazione, ma non in una parte non elaborata, ma in una parte attiva.

Quest'ultimo può anche essere una soluzione se devi affrontare i mutevoli requisiti in una fase di prototipazione purché le conoscenze sui requisiti reali non si siano stabilizzate. In questo caso, una opzione di attivazione potrebbe essere una soluzione fattibile.

    
risposta data 08.10.2013 - 08:50
fonte
1

Vorrei estendere l'idea della risposta ora cancellata di @MathewFoscarini.

Crea un'astrazione (un'interfaccia nel caso più semplice) attorno al codice in questione. Rendi il codice in questione un'implementazione e crea una nuova implementazione che corrisponda ai nuovi requisiti. Se necessario, sposta la vecchia implementazione nel proprio modulo, in modo che non venga impacchettata per la produzione.

Riassumendo: ti stai imbattendo in una violazione del principio di open closed, perché stai spesso cambiando i dettagli di implementazione di una classe. Per risolvere questo problema è necessario introdurre un'interfaccia comune e configurare la propria applicazione per utilizzare l'implementazione corretta.

    
risposta data 08.10.2013 - 08:32
fonte
0

Il mio approccio pragmatico è quello di dire la sua fine per commentare il codice e verificarlo. Questo ha il vantaggio di poter vedere il codice precedente immediatamente presente a tutti coloro che cercano (come sappiamo, i bug vengono spesso introdotti e trovati immediatamente , quindi se lasci un po 'di vecchio codice lì, chiunque cerchi un bug sarà molto più incline a individuare dove potrebbe essere il cambiamento offensivo.

Tuttavia, ho anche pensato che qualsiasi codice commentato possa essere cancellato quando lo verifichi per la modifica. Quindi se ottieni del codice e vedi il codice commentato, allora è passato alla sua utilità e può essere cancellato in modo sicuro. Il codice commentato dovrebbe quindi vivere solo per 1 check-in. (ovviamente, non si effettua il check-in del codice che ha rimosso solo il codice commentato, solo se si cambia l'area circostante, poiché non si dovrebbe mai vedere quel codice commentato se non si deve guardare nuovamente il codice).

Ovviamente è una linea guida molto approssimativa, e commento solo un codice che penso sia comunque un po 'peloso.

    
risposta data 10.10.2013 - 13:44
fonte
0

Se sai che il codice può essere riutilizzato, lo rifattero come metodo inutilizzato e documenterei che è disponibile per un possibile uso futuro.

Se deve o deve essere rimosso, allora prenderei in considerazione l'utilizzo di qualche forma di tagging o un commento standard come REMOVED: , che è ricercabile in seguito.

    
risposta data 10.10.2013 - 13:56
fonte
0

Penso che non pensi che dovresti operare secondo la premessa che; Potremmo averne bisogno. Se non ce l'abbiamo e ne abbiamo bisogno ci sarà questa quantità di tempo sproporzionata per ricreare la soluzione. Questa soluzione è così grande che nessuno ci penserà mai più.

Se possibile, scrivi un test unitario che passa in base a questa / e linea / e di codice escluso. Qualcosa sul test dovrebbe dirti perché non è più una buona idea avere questo codice lì dentro.

Ora lo hai documentato in: controllo del codice sorgente, test e qualsiasi altra documentazione, progetto o tracciamento delle richieste.

L'obiettivo non è trovare il modo più conveniente per riaggiungere, ma affidarsi e rivedere tutte le risorse su una particolare area dell'applicazione prima di apportare qualsiasi modifica. Non è sufficiente utilizzare solo la memoria o prompt non necessari nel codice. Chissà se è cambiato qualcos'altro che rende il codice salvato inutile.

YAGNI

    
risposta data 10.10.2013 - 18:27
fonte

Leggi altre domande sui tag