Buona idea per inserire numeri di bug in un commento all'inizio del file sorgente? [chiuso]

È buona norma inserire i numeri di bug nel file stesso all'interno di un commento di intestazione?

I commenti sarebbero simili a questo:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Sembra utile, ma è considerata una cattiva pratica?

L'ho già visto in precedenza, sia manualmente dagli autori che automaticamente da script e trigger integrati con i sistemi di controllo della versione per aggiungere al file autore, commento sul check-in e informazioni sulla data.

Penso che entrambi i metodi siano piuttosto terribili per due ragioni principali. Innanzitutto, aggiunge confusione e rumore al file, specialmente quando questi commenti invecchiano e diventano irrilevanti per lo stato corrente del file. In secondo luogo, si tratta di informazioni duplicate rispetto a quelle già gestite nel sistema di controllo della versione e, se si utilizza un moderno sistema di controllo della versione che supporta i set di modifiche, in realtà sta perdendo informazioni sulle modifiche.

Semmai, considera l'integrazione con il tuo sistema di localizzazione dei difetti. Alcuni strumenti consentono di collegare un difetto o un numero ID attività in un commento di check-in a un elemento nello strumento di monitoraggio. Se nello strumento sono presenti tutti i difetti, le richieste di miglioramento e le attività lavorative, è possibile fornire tale collegamento. Naturalmente, questo ha il rovescio della medaglia di una dipendenza da quegli strumenti per il progetto.

Esiste esattamente un caso in cui lo farei, vale a dire come parte di un avvertimento per i futuri programmatori: "Non chiamare la funzione foo() direttamente la qui; questo ha causato il bug # 1234, vale a dire ...", e quindi una breve descrizione del il bug segue.

E se il codice è cambiato in modo tale da non essere tentato di chiamare foo()direttamente, rimuovi quel commento. Avrebbe solo irritato e fatto saltare in aria il codice.

È una pratica del tutto orribile. Aggiunge uno sforzo per ottenere un effetto che è pura duplicazione; in altre parole, l'unica cosa che aggiunge al solo utilizzo dei log di commit è la possibilità di creare incoerenze. I tuoi file sorgente diventano ingombri di quantità illimitate di cose che non guardi mai.

L'unico aspetto positivo che posso discernere è che potresti ricostruire la cronologia di origine senza accedere al controllo della versione, ad esempio quando studi una stampa. Ma pochissime persone sono abbastanza competenti per seguire le complessità dello sviluppo del software, mentre allo stesso tempo non sono in grado di comprendere il controllo della versione.

No.

Questo è ciò che le persone hanno fatto prima di usare un sistema di controllo della versione (cioè quando il codice sorgente era solo un backup nei file zip).

È, IMHO, una pessima idea. Dopo la revisione numero 100, avrai il 90% di commenti e il 10% di codice. Non lo considero pulito e leggibile.

L'unico punto in questo che vedo è quando devi scambiare il tuo codice tra SCC e, per qualsiasi motivo, non puoi trasferire la cronologia tra i due sistemi (ma anche quando salvi i commenti della cronologia in quel modo, perderai la cronologia delle differenze anche, quindi salvare i commenti ti aiuterà solo un po ').

Vedo che tutti sono contrari all'idea e hanno fornito una ragione storica (era pre-controllo dell'era) del perché le persone lo facessero.

Tuttavia, nella mia attuale azienda, gli sviluppatori di database stanno seguendo questa pratica e taggano ulteriormente il numero di bug attorno al pezzo di codice. A volte lo trovo utile quando vedi un bug nel codice e puoi scoprire immediatamente la correzione di bug che ha introdotto questo problema. Se non abbiamo tali informazioni nel mio pacchetto di database, non sarà certamente facile trovare la causa principale di tale implementazione.

Sì, ingombra il codice, ma aiuta a trovare il motivo per cui quel pezzo di codice è lì.

Uno dei punti del test Joel è

Hai un database di bug?

Tali informazioni potrebbero essere conservate in un database di bug se si ritiene che siano importanti, ma sarebbero solo rumorose nei commenti.

Penso che tu abbia due problemi qui. Innanzitutto, perché dovresti semplicemente fare affidamento sul diff quando la maggior parte dei sistemi ti consente di inserire commenti di revisione? Come buoni commenti in codice, scopri perché la modifica è stata apportata e non solo la modifica stessa.

In secondo luogo, se si dispone di questa capacità, è consigliabile metterli tutti nello stesso posto. Non è necessario cercare nel file le linee di codice contrassegnate che non sono più necessarie. I commenti all'interno del codice di lavoro sono lì per dirti perché è codificato in questo modo.

Una volta messo in pratica, le abitudini formate rendono la base di codice più facile da lavorare per tutti.

Il rilevamento di bug e funzionalità associato e il motivo per cui stai modificando questo file, possono darti un'idea di quanto sia necessario approfondire la cronologia e possibilmente guardare le differenze. Ho ricevuto una richiesta per "Tornare alla formula originale". Sapevo bene dove andare nella cronologia delle revisioni e ho solo recensito una o due differenze.

Personalmente, il codice annotato sembra un work in progress per un problema che viene risolto da tentativi ed errori. Elimina questo pasticcio dal codice di produzione. Essere in grado di scivolare facilmente dentro e fuori le righe di codice rende solo più facile essere confusi.

Se non hai VCS con messaggi di commit e nessun sistema di tracciamento dei bug con un'opzione per lasciare commenti, è un'opzione, e non quella ottimale, per tenere traccia delle modifiche.
Meglio avere un foglio di calcolo con quelle informazioni, o se ti trovi in ​​un ambiente senza tali "lussi", un file di testo che si trova da qualche parte vicino alle tue fonti.
Ma consiglio vivamente se ti trovi in ​​un ambiente simile per iniziare a costruire un caso per investire in un sistema VCS e di tracciamento dei bug :)

Tienilo a mente: il codice è spesso più lungo degli strumenti che lo supportano. Detto diversamente, i tracker dei problemi, il controllo della versione e tutti gli altri script si evolveranno nel corso dello sviluppo. Le informazioni si perdono.

Mentre sono d'accordo, il disordine dei file è fastidioso, aprire un file e comprenderne la storia senza ricorrere all'uso degli strumenti, è sempre stato molto utile, specialmente se sto mantenendo il codice.

Personalmente, penso che ci sia spazio sia per gli strumenti che per il registro nel codice.

So che Git non lo fa e la semplice risposta è "perché mai andrebbe lì?"

È un design meno modulare in generale. Con questa soluzione, ora i file sono un mix tra contenuto e metadati. Amazon S3 è un altro esempio di servizio per l'archiviazione di file che non aggiunge front-matter YAML o simili ai file.

Ogni utente di un file deve prima elaborarlo attraverso il sistema di controllo della versione. Si tratta di un accoppiamento stretto, ad esempio il tuo IDE preferito si romperà se non supporta il tuo VCS.

No, non è una buona pratica tenere traccia delle correzioni dei bug come commenti nel codice. Questo genera solo disordine.

Dico lo stesso anche per il messaggio sul copyright che hai citato. Se nessuno al di fuori della tua azienda vedrà mai questo codice, non c'è motivo di includere un messaggio sul copyright.

Se si utilizza il software di monitoraggio della versione ( Git , SVN , ecc.), È necessario includere tali note nei messaggi di commit. Nessuno vuole scavare tra le intestazioni di ogni file di codice per generare note di rilascio o vedere una panoramica delle modifiche apportate. Questi registri delle modifiche devono essere archiviati tutti insieme, nella cronologia di tracciamento della versione, nel rilevatore di difetti o in entrambi.

Se stai cercando una buona lettura su questo argomento, ti consiglio il capitolo quattro di Clean Code .

Penso che ci siano altri elementi in questa discussione che sono spesso dimenticati ma sono casi in cui alcuni commenti di revisione sono rapidi per una squadra.

Quando si lavora in un ambiente di team con una base di codice condivisa e in cui diversi membri del team lavorano potenzialmente nelle stesse aree di codice, inserire un breve commento di revisione nell'ambito (metodo o classe) corretto indicando che è stata apportata una modifica può essere molto utile per risolvere rapidamente i conflitti di unione o di registrazione.

Allo stesso modo, quando si lavora in un ambiente in cui sono coinvolti diversi rami (funzionalità), per una terza persona (build master) è più facile identificare cosa fare per risolvere potenziali conflitti.

Ogni volta che devi allontanarti dall'IDE e chiedere a qualcuno perché hanno cambiato qualcosa, ciò disturba la produttività di entrambi i membri del team. Una breve nota nell'ambito corretto può aiutare a ridurre o eliminare la maggior parte di questa interruzione.

Qualsiasi informazione sui bug direttamente associata a un pezzo di codice, diventa irrilevante quando l'integrità dell'intera modifica viene modificata da una correzione successiva.

Una volta era comune aggiungere informazioni nel riepilogo delle funzioni quando dovevamo fare affidamento su strumenti esterni (ad esempio javadocs) per creare note di rilascio dal codice. È principalmente inutile o ridondante con gli strumenti di controllo della versione moderna.

Potrebbe avere senso solo come un commento in un pezzo di codice molto modulare, se si dovesse ricorrere a un codice oscuro o non stellare che i futuri sviluppatori sarebbero tentati di cambiare - ignari del motivo che sta dietro - come in una soluzione alternativa a un bug / difetto della libreria.

Sicuramente non metterei tali informazioni all'inizio del file - di solito una cosa del genere appartiene a un sistema di ticket.

Vi sono tuttavia alcuni casi in cui i riferimenti al sistema dei biglietti e / o altra documentazione hanno senso. Ad esempio, se esiste una lunga spiegazione del progetto o una descrizione delle alternative. O informazioni su come testare le cose o spiegazioni sul perché sia ​​stato fatto esattamente in questo modo. Se è breve, appartiene al file stesso; se è lungo e / o riguarda un'immagine più grande, probabilmente vorrai metterlo altrove e fare riferimento a esso.

Il progetto a cui sono attualmente assegnato al lavoro aveva questo tipo di elenco di numeri di bug all'inizio di ogni file; tuttavia, nessuno degli sviluppatori ancora presenti nel progetto lo accoda più. La maggior parte di loro pensa che sia uno spreco di spazio inutile, in quanto è di gran lunga inferiore al tracciamento dei bug di commit in un file utilizzando il nostro sistema di controllo della versione.

In alcuni file critici che hanno subito molte correzioni e miglioramenti, questi elenchi sono diventati così grandi che è necessario scorrere oltre per ottenere il codice. Quando si grepping questi elenchi possono causare diversi falsi positivi in ​​quanto un titolo breve o una breve descrizione sono elencati con ciascuno.

In breve, questi elenchi sono nella migliore delle ipotesi inutili e nella peggiore delle ipotesi uno spreco di spazio enorme e caotico che rende il codice più difficile da cercare e individuare.