È una cattiva pratica non eliminare i file ridondanti immediatamente da VCS ma contrassegnarli invece come "Da eliminare" con i commenti prima?


53

Volevo sapere se il modo in cui gestisco i file di origine che devono essere eliminati dal controllo versione potrebbe essere considerato una cattiva pratica.

Voglio spiegartelo in base a quell'esempio:

Di recente mi sono molto arrabbiato perché ho dovuto sistemare in modo noioso le classi Java in un programma che era sostanzialmente un codice morto, ma non era documentato da nessuna parte e non commentato in quelle classi Java. Certo, dovevano essere eliminati, ma prima di eliminare cose così ridondanti ho l'abitudine - qualcuno potrebbe dire strano -:

Non elimino immediatamente tali file ridondanti tramite SVN-> Elimina (sostituisci con il comando di eliminazione del tuo sistema di controllo versione scelto) ma inserisco invece i commenti in quei file (mi riferisco sia in testa che a piè di pagina) a cui stanno andando essere cancellato + il mio nome + la data e, soprattutto, PERCHÉ SONO ELIMINATI (nel mio caso, perché erano morti, codice confuso). Quindi li salvo e li commetto per il controllo della versione. La prossima volta quando devo impegnare / archiviare qualcosa nel progetto per il controllo della versione, premo SVN-> Elimina e poi alla fine vengono eliminati nel Controllo versione - comunque ovviamente ripristinabili tramite le revisioni e questo è il motivo per cui ho adottato questa abitudine.

Perché farlo invece di eliminarli immediatamente?

La mia ragione è che voglio avere marcatori espliciti almeno nell'ultima revisione in cui esistevano quei file ridondanti, perché meritavano di essere cancellati. Se li elimino immediatamente, vengono eliminati ma non è documentato in alcun modo il motivo per cui sono stati eliminati. Voglio evitare uno scenario tipico come questo:

"Hmm ... perché quei file sono stati cancellati? Ho funzionato bene prima." (Preme 'ripristina' -> il tipo che è stato ripristinato è scomparso per sempre o non è disponibile nelle prossime settimane e il prossimo cessionario deve scoprire noiosamente come sono i file)

Ma non noti perché quei file sono stati eliminati nei messaggi di commit?

Certo che lo faccio ma a volte un messaggio di commit non viene letto dai colleghi. Non è una situazione tipica che quando provi a capire il codice (nel mio caso morto) controlli prima il registro di controllo versione con tutti i messaggi di commit associati. Invece di eseguire la scansione del registro, un collega può vedere subito che questo file è inutile. Le fa risparmiare tempo e sa che questo file è stato probabilmente ripristinato male (o almeno solleva una domanda.


120
Stai essenzialmente cercando di replicare il lavoro del tuo sistema di controllo versione direttamente nel file. Fare una cosa del genere avrebbe sicuramente sollevato una bandiera nella mia testa. Se i tuoi colleghi non leggono i messaggi di commit e resuscitano un file che è stato giustamente eliminato e passa la revisione del codice, c'è sicuramente qualcosa di sbagliato nel tuo team ed è una grande opportunità per insegnarli meglio.
Vincent Savard,

6
@GregBurghardt Sembra una buona domanda su una cattiva idea. Forse le persone effettuano il downvoting in base alla seconda parte (quando, IMO, dovrebbero essere votate per la prima)?
Ben Aaronson,

13
"La prossima volta che devo eseguire il commit / check in qualcosa nel progetto per il controllo della versione, premo SVN-> Elimina" Stai dicendo che li elimini in un commit (potenzialmente) del tutto indipendente?
Kevin,

21
Certo che lo faccio ma a volte un messaggio di commit non viene letto dai colleghi. - se non stanno controllando il messaggio di commit, si può presumere che non siano interessati al motivo per cui il file è stato rimosso ... altrimenti dovrebbero controllare il messaggio di commit.
Formica P

9
Se voglio sapere perché un file scomparso dal mio checkout VCS, guarderò nella cronologia delle modifiche prima , e se questo non spiega le cose, io leggerò la discussione che è accaduto quando la cancellazione è stato rivisto. (Se non si dispone di un processo di revisione del codice che subisce ogni modifica, si hanno problemi più grandi.) E se ciò non è ancora chiaro, parlerò con chiunque abbia eliminato il file. Potrei guardare i precedenti contenuti del file per provare a scoprire cosa faceva prima, ma non per una spiegazione della cancellazione.
zwol,

Risposte:


110

Il problema con l'aggiunta di un commento a un file che dovrebbe essere eliminato, invece di eliminarlo nel controllo del codice sorgente e inserendo la spiegazione lì, è il presupposto che se gli sviluppatori non leggono i messaggi di commit leggeranno sicuramente i commenti nel codice sorgente.

Dal punto di vista di un estraneo, questa metodologia sembra essere radicata in una visione molto conservativa del controllo del codice sorgente.

"Cosa succede se elimino questo file inutilizzato e qualcuno ne ha bisogno?" qualcuno potrebbe chiedere.

Stai utilizzando il controllo del codice sorgente. Annulla la modifica o, meglio ancora, parla con la persona che ha eliminato il file (comunica).

"Cosa succede se elimino il file morto, quindi qualcuno inizia a usarlo di nuovo e apporta le modifiche?" qualcun altro potrebbe chiedere.

Ancora una volta, stai usando il controllo del codice sorgente. Avrai un conflitto di unione che una persona deve risolvere. La risposta qui, come con l'ultima domanda, è di comunicare con i tuoi compagni di squadra.

Se dubiti davvero che un file debba essere rimosso, comunica prima di eliminarlo dal controllo del codice sorgente. Forse solo di recente ha smesso di essere utilizzato, ma una funzionalità imminente potrebbe richiederlo. Non lo sai, ma uno degli altri sviluppatori potrebbe.

Se deve essere rimosso, rimuoverlo. Tagliare il grasso dalla base di codice.

Se hai creato un "oopsie" e hai effettivamente bisogno del file, ricorda che stai usando il controllo del codice sorgente in modo da poter recuperare il file.

Vincent Savard, in un commento sulla domanda, ha dichiarato:

... Se i tuoi colleghi non leggono i messaggi di commit e resuscitano un file che è stato giustamente eliminato e passa la revisione del codice, c'è sicuramente qualcosa di sbagliato nel tuo team ed è una grande opportunità per insegnarli meglio.

Questo è un buon consiglio. Le revisioni del codice dovrebbero catturare questo tipo di cose. Gli sviluppatori devono consultare i messaggi di commit quando viene apportata una modifica imprevista a un file o quando un file viene rimosso o rinominato.

Se i messaggi di commit non raccontano la storia, anche gli sviluppatori devono scrivere messaggi di commit migliori.

La paura di eliminare il codice o eliminare i file è indicativo di un problema più profondo e sistemico con il processo:

  • Mancanza di accurate verifiche del codice
  • Mancanza di comprensione su come funziona il controllo del codice sorgente
  • Mancanza di comunicazione di squadra
  • Messaggi di commit scadenti da parte degli sviluppatori

Questi sono i problemi da affrontare, quindi non hai la sensazione di lanciare sassi in una serra quando elimini codice o file.


3
"supponiamo che se gli sviluppatori non leggono i messaggi di commit, sicuramente leggeranno i commenti nel codice sorgente." Penso che questo sia un presupposto abbastanza buono. Uno sviluppatore che modifica un file deve effettivamente guardare il file per eseguire l'attività, mentre non c'è nulla che costringa a guardare la cronologia del controllo del codice sorgente.
AShelly,

7
@AShelly: un'attività di sviluppo è raramente quella di modificare un commento. Le attività comportano la modifica del codice, che è ciò su cui si concentra lo sviluppatore, non i commenti.
Greg Burghardt,

21
@AShelly Solo perché devono aprire un file non significa che leggeranno un particolare commento in alto. Il pubblico target per questo cambiamento è il tipo di sviluppatore più ignaro, il tipo che pensa che i suoi bisogni siano gli unici bisogni e tutto dovrebbe ruotare attorno a loro. È improbabile che questi leggano il tuo cortese commento. Peggio ancora, probabilmente lo leggeranno e poi torneranno semplicemente alla prossima versione più vecchia.
Cort Ammon,

5
@AShelly - ad esempio, di solito apro i file in una posizione. In VS posso aprire direttamente un metodo usando i menu a discesa in alto o il menu contestuale "vai alla definizione". Non vedrei mai la parte superiore del file. Anche in Sublime Text apro spesso una riga. La loro finestra di dialogo aperta users.rb: 123 aprirebbe gli utenti.rb direttamente alla riga 123. Molti editor di codice hanno opzioni molto simili.
Coteyr,

2
Oltre a quanto sopra, più è complesso svolgere attività di pulizia come questa, meno è probabile che le persone le eseguano regolarmente. Se riesci a cavartela più semplice, diminuisce "l'energia di attivazione" per te e tutti gli altri. Ciò è particolarmente importante se stai cercando di incoraggiare un cambio di pratica per gli altri membri del team. Più complessa è la procedura, più è difficile ottenere il buy-in.
xdhmoore,

105

Sì, è una cattiva pratica.

Dovresti inserire la spiegazione per la cancellazione nel messaggio di commit quando commetti la cancellazione dei file.

I commenti nei file di origine dovrebbero spiegare il codice come appare attualmente . I messaggi di commit dovrebbero spiegare perché sono state apportate le modifiche nel commit, quindi la cronologia di commit sul file spiega la sua cronologia.

Scrivere commenti che spiegano le modifiche direttamente nella fonte stessa renderà il codice molto più difficile da seguire. Pensaci: se commenti nel file ogni volta che modifichi o elimini il codice, presto i file verranno sommersi con commenti sulla cronologia delle modifiche.


6
Forse aggiungi la risposta alla domanda: è una cattiva pratica? Sì, perché ....
Juan Carlos Coto,

1
A volte faccio lo stesso (come OP) perché è più facile decommentare che ripristinare. In rari casi, anche se il codice viene compilato e superato i test automatici, c'è una ragione per l'esistenza di quel codice che ho trascurato che il tester manuale avrebbe individuato. In questo raro scenario, invece di subire gravi sofferenze o di ripristinare le cose in seguito a diversi commit, ho semplicemente decommentato il codice (e rivisto il modo in cui può essere migliorato)
Andrew Savinykh

2
@AndrewSavinykh È diverso, stai commentando il codice che non sei ancora sicuro di voler eliminare.
Smetti di fare del male a Monica il

6
@AndrewSavinykh “grande dolore o ripristino di cose che più commette più tardi” - Mi chiedo quale controllo di versione usi; questo non dovrebbe essere un grande dolore. Certamente non è in Git, almeno non dopo averlo fatto un paio di volte e aver imparato cosa cercare ... e purché la tua storia non sia ostruita da inutili impegni avanti e indietro che ti danno è in conflitto ogni altra unione. E si impegna a commentare qualcosa è piuttosto incline a farlo ...
leftaroundabout

4
@AndrewSavinykh sì, e non è come se non avessi riscontrato questi problemi - progetti i cui manutentori non hanno mai realmente lavorato con il controllo della versione e hanno messo molte informazioni nei commenti che avrebbero dovuto essere messaggi di commit, invece hanno aggiunto nuovi manuali-annulla-commit invece di corretto ripristino, ecc. Lo stato risultante del repository ha reso divertente un sacco di conflitti in ogni più grande riforme ... Ma, e questo è il mio punto, questi problemi sono spesso in gran parte causati da soluzioni alternative come quella che difendi qui.
lasciato il

15

Secondo me entrambe le opzioni non sono buone pratiche , al contrario di cattive pratiche:

  1. L'aggiunta di commenti aggiunge qualsiasi valore se qualcuno capita di leggere quei commenti.
  2. La semplice eliminazione dal VCS, (con un motivo nella descrizione della modifica), può influire su un risultato critico e molte persone non leggono la descrizione della modifica, soprattutto quando sono sotto pressione.

La mia pratica preferita - in gran parte dovuta al fatto di essere stata morsa più volte nel corso degli anni, tenendo presente che non sempre sai dove o da chi viene utilizzato il tuo codice - è di:

  1. Aggiungi un commento affermando che è un candidato per la cancellazione e una deprecazione #warning o simile, (la maggior parte delle lingue ha una sorta di tale meccanismo, ad esempio in Java , nel peggiore dei casi printsarà sufficiente una dichiarazione o simile), idealmente con una sorta di scala temporale e con i dettagli di contatto. Questo avviserà chiunque stia ancora utilizzando il codice. Questi avvisi sono normalmente all'interno di ogni funzione o classe se tali cose esistono .
  2. Dopo un po 'di tempo aggiorna l'avviso a un ambito di file standard #warning(alcune persone ignorano gli avvisi di deprecazione e alcune catene di strumenti non visualizzano tali avvisi per impostazione predefinita).
  3. Sostituire in seguito l'ambito del file #warningcon un #erroro equivalente: questo interromperà il codice al momento della creazione ma può, se assolutamente necessario, essere rimosso ma la persona che lo rimuove non può ignorarlo. (Alcuni sviluppatori non leggono o affrontano alcun avviso o ne hanno così tanti che non riescono a separare quelli importanti).
  4. Infine, contrassegnare i file (o alla data di scadenza), come eliminati nel VCS.
  5. Se si elimina un intero pacchetto / libreria / ecc. In fase di avviso, aggiungerei un file README.txt o README.html o simile con le informazioni su quando e perché è pianificato di sbarazzarsi del pacchetto e lasciare solo quel file, con un cambiare per dire quando è stato eliminato, come unico contenuto del pacchetto per qualche tempo dopo aver rimosso il resto del contenuto.

Un vantaggio di questo approccio è che alcuni sistemi di versioning (CVS, PVCS, ecc.) Non rimuoveranno un file esistente al momento del checkout se è stato eliminato nel VCS. Offre inoltre agli sviluppatori coscienziosi, coloro che risolvono tutti i loro avvertimenti, molto tempo per affrontare il problema o fare appello alla cancellazione. Inoltre costringe i restanti sviluppatori a guardare almeno l'avviso di cancellazione e lamentarsi molto .

Si noti che #warning/ #errorè un meccanismo C / C ++ che causa un avviso / errore seguito dal testo fornito quando il compilatore incontra quel codice, java / java-doc ha @Deprecatedun'annotazione per emettere un avviso sull'uso e @deprecatedper fornire alcune informazioni, ecc. Ci sono ricette per fare simili in Python e ho visto assertusate per fornire informazioni simili a quelle #errornel mondo reale.


7
In particolare, poiché questa domanda menziona Java, utilizzare il @deprecatedcommento JavaDoc e l' @Deprecatedannotazione .
200_successo

8
Questo sembra più appropriato quando vuoi sbarazzarti di qualcosa ancora in uso. L'avvertimento può rimanere attivo fino a quando tutti gli utilizzi non sono stati eliminati, ma una volta che il codice è scaduto dovrebbe essere eliminato immediatamente.
Andy,

6
@Andy Uno dei problemi con il codice del tipo di libreria, specialmente in Open Source o in organizzazioni di grandi dimensioni, è che potresti pensare che il codice sia morto ma scopri che è in uso attivo in uno o più luoghi che personalmente non hai mai immaginato in cui era in uso. A volte il codice deve essere eliminato, perché è davvero male o include rischi per la sicurezza, ma semplicemente non sai se e dove viene utilizzato.
Steve Barnes,

1
@ 200_success thanks - il mio background in C / C ++ mostra - aggiunto alla risposta.
Steve Barnes,

1
@SteveBarnes Forse, ma non è questo ciò che l'OP chiede. Ha verificato che il codice è morto.
Andy,

3

Sì, direi che è una cattiva pratica, ma non perché è nei file rispetto al messaggio di commit. Il problema è che stai cercando di apportare una modifica senza comunicare con il tuo team.

Ogni volta che si apportano modifiche al trunk, aggiungendo, eliminando o modificando i file in qualsiasi modo, è necessario, prima di tornare al trunk, parlare di tali cambiamenti direttamente con un membro (o membri) del team che sarebbe direttamente ben informato su di loro (essenzialmente, discuti di ciò che inseriresti in quelle intestazioni direttamente con i tuoi compagni di squadra). Ciò assicurerà che (1) il codice che stai eliminando debba davvero essere eliminato e che (2) il tuo team avrà molte più probabilità di sapere che il codice è stato eliminato e quindi non provare a ripristinare le tue eliminazioni. Per non parlare del fatto che otterrai anche il rilevamento di bug e simili per il codice che aggiungi.

Ovviamente, quando cambi grandi cose, dovresti anche inserirle nel messaggio di commit, ma poiché ne hai già discusso, non deve essere la fonte di annunci importanti. La risposta di Steve Barnes affronta anche alcune buone strategie da utilizzare se il potenziale pool di utenti per il tuo codice è troppo grande (ad esempio, usando i marcatori obsoleti della tua lingua invece di eliminare i file all'inizio).

Se non vuoi andare così a lungo senza impegnarti (cioè il tuo cambiamento ha più senso come diverse revisioni), è una buona idea creare un ramo dal tronco e impegnarsi nel ramo, quindi unire nuovamente il ramo nel tronco quando il il cambiamento è pronto. In questo modo, VCS sta ancora eseguendo il backup del file, ma le modifiche non influiscono in alcun modo sul trunk.


1

Un problema correlato a progetti che si basano su più piattaforme e configurazioni. Solo perché mi determino che è morto non significa che sia una corretta determinazione. Nota che un morto in uso potrebbe ancora significare dipendenza vestigiale che deve ancora essere eliminata e che alcuni potrebbero essersi persi.

Quindi (in un progetto C ++) ho aggiunto

#error this is not as dead as I thought it was

E ho controllato. Aspetta che riesca a ricostruire tutte le piattaforme normali e che nessuno si lamenta. Se qualcuno lo trovasse, sarebbe facile rimuovere una riga invece di essere sconcertato da un file mancante.

Concordo in linea di principio sul fatto che i commenti che menzioni stanno duplicando la funzione che dovrebbe essere fatta nel sistema di gestione delle versioni . Ma potresti avere ragioni specifiche per soppiantarlo. Non conoscere lo strumento VCS non è uno di questi.


-1

Sul continuum delle cattive pratiche, questo è piuttosto secondario. Lo farò occasionalmente, quando voglio controllare un ramo ed essere in grado di vedere il vecchio codice. Questo può facilitare il confronto con il codice di sostituzione. Di solito ricevo un commento di revisione del codice "cruft". Con una piccola spiegazione passo la recensione del codice.

Ma questo codice non dovrebbe durare a lungo. In genere elimino all'inizio dello sprint successivo.

Se hai colleghi che non leggono i messaggi di commit o non ti chiedono perché hai lasciato il codice nel progetto, il tuo problema non è di cattivo stile di codifica. Hai un problema diverso.


questo non sembra offrire nulla di sostanziale rispetto ai punti formulati e spiegati nelle precedenti 6 risposte
moscerino del

-3

puoi anche riformattare la classe e rinominarla con un prefisso in UNUSED_Classname prima di eseguire la tua acrobazia. Quindi dovresti anche eseguire direttamente l'operazione di eliminazione

  • Passaggio 1: rinomina la classe, aggiungi il tuo commento, esegui il commit
  • Passaggio 2: elimina il file e esegui il commit

Se è un codice morto, eliminalo. Tutti ne hanno bisogno, possono tornare indietro, ma il passaggio di rinomina impedirà loro di usarlo direttamente senza pensare.

Insegna anche alle persone come guardare tutti i messaggi di commit per un file, alcune persone non sanno nemmeno che sia possibile.


6
"Refactoring" non significa davvero quello che pensi che faccia
Nik Kyriakides il

6
Non è necessario rinominare la classe / metodo per assicurarsi che non sia in uso, l'eliminazione funziona altrettanto bene. Invece la procedura è la stessa di qualsiasi altra modifica: 1) elimina il codice morto , 2) esegui i test , 3) se superano, esegui il commit con il commento .
Schwern,

1
@ user275398 Penso anche che rinominare i file sia davvero troppo. E anche dal punto di vista tecnologico, SVN tratta la ridenominazione come se il file fosse cancellato e creato con un nuovo nome, quindi hai una rottura nella storia. Se si ripristinasse il file rinominato e si guardasse nel registro SVN di esso, la cronologia precedente alla ridenominazione non è disponibile. Per questo devi ripristinare il file con il vecchio nome. Il refactoring è comunque qualcos'altro, il refactoring sta organizzando il codice esistente in una nuova struttura.
Bruder Lustig,

@BruderLustig: un buon software certamente non lo farà. Git ha git mv, che tiene traccia della storia. Anche Mercurial ha hg mv. Sembra che svn movedovrebbe funzionare anche per SVN?
wchargin,

@wchargin No, git mvsposta semplicemente il file e mette in scena una cancellazione del file e una creazione del file. Tutto il tracking delle mosse avviene quando corri git log --followe simili. gitnon ha modo di rintracciare i nomi, in realtà non tiene traccia delle modifiche ; tiene invece traccia degli stati al momento del commit e scopre cosa è cambiato nel momento in cui si ispeziona la cronologia.
Maaartinus,
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.