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

Ho visto questo fatto prima, sia manualmente dagli autori e automaticamente da script e trigger integrati con i sistemi di controllo delle versioni per aggiungere all'autore, il commento di check-in e le informazioni sulla data al file.

Penso che entrambi i metodi siano piuttosto terribili per due motivi principali. Innanzitutto, aggiunge clutter e rumore al file, soprattutto perché questi commenti invecchiano e diventano irrilevanti rispetto allo stato corrente del file. In secondo luogo, si tratta di informazioni duplicate provenienti da ciò che è già stato mantenuto nel sistema di controllo della versione e, se si utilizza un sistema di controllo di versione moderno che supporta i set di modifiche, in realtà sta perdendo informazioni sulle modifiche.

Se possibile, considera l'integrazione con il tuo sistema di tracciamento dei difetti. Alcuni strumenti consentono di collegare un difetto o un numero ID dell'attività in un commento di check-in a un elemento nello strumento di tracciamento. Se hai tutti i tuoi difetti, richieste di miglioramento e attività lavorative nello strumento, puoi fornire il collegamento in questo modo. Ovviamente, ciò comporta il lato negativo di una dipendenza da quegli strumenti per il progetto.

Esiste esattamente un caso in cui vorrei farlo, vale a dire come parte di un avviso per i futuri programmatori: "Non chiamare la funzione foo() qui direttamente, ciò ha causato il bug # 1234, cioè ...", e quindi segue una breve descrizione del bug.

E se il codice è cambiato in modo che non ci sia la tentazione di chiamare direttamente foo() , rimuovi quel commento. Sarebbe solo irritare e far esplodere 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 semplicemente utilizzando i registri di commit è la possibilità di creare incoerenze. I tuoi file sorgente sono ingombri di quantità illimitate di cose che non guardi mai.

L'unico vantaggio che posso discernere è che è possibile ricostruire la cronologia della fonte senza accedere al controllo della versione, ad es. quando si studia una stampa. Ma pochissime persone sono abbastanza competenti per seguire la complessità dello sviluppo del software, mentre allo stesso tempo non riescono a capire il controllo della versione.

No.

Questo è ciò che le persone facevano prima che usassero un sistema di controllo della versione (ad esempio quando il codice sorgente era solo backup in file zip).

È, IMHO, una pessima idea. Dopo la revisione numero 100, avrai il 90% di commenti e il 10% di codice. Non lo considererei 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 questo modo, perdi la cronologia delle differenze, 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 sorgente) del perché le persone lo facevano.

Tuttavia, nella mia attuale azienda, gli sviluppatori di database stanno seguendo questa pratica e taggano inoltre il numero di bug attorno al pezzo di codice. A volte trovo questo utile quando si vede un errore nel codice e si può immediatamente scoprire la correzione di bug che ha introdotto questo problema. Se non abbiamo queste informazioni nel mio pacchetto di database, sicuramente non sarà facile trovare la causa principale di tale implementazione.

Sì, ingombra il codice, ma aiuta a trovare la ragione del perché quel pezzo di codice è lì.

Uno dei punti del test di Joel è

Do you have a bug database?

Queste informazioni potrebbero essere conservate in un database di bug se ritieni che siano importanti, ma farebbero solo rumore nei commenti.

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

In secondo luogo, se si dispone di questa capacità, è buona norma metterli tutti nello stesso posto. Non vi è alcuna necessità di consultare il file per le righe di codice evidenziate che non sono più necessarie. I commenti all'interno del codice funzionante sono lì per dirti perché è codificato in questo modo.

Una volta messo in pratica, le abitudini formate rendono il codice base più facile da utilizzare per tutti.

Il bug associato e il tracciamento delle funzionalità insieme al 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 "Ripristinare la formula originale". Sapevo esattamente dove andare nella cronologia delle revisioni e ho esaminato solo una o due diff.

Personalmente, il codice evidenziato sembra un work in progress per un problema che viene risolto per tentativi ed errori. Ottieni questo casino dal codice di produzione. Essere in grado di infilare facilmente le linee di codice dentro e fuori rende solo più facile essere confusi.

Se non hai VCS con messaggi di commit e nessun sistema di tracciamento 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 tali informazioni, o se ci si trova in un ambiente senza tali "lussi", un file di testo che si trova da qualche parte vicino alle proprie fonti.
Ma ti consiglio caldamente di trovarti in un simile ambiente per iniziare a costruire un caso per investire in un VCS e un sistema di tracciamento dei bug:)

Ricorda questo: 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.

Anche se sono d'accordo, la confusione di file è fastidiosa, aprire un file e comprenderne la cronologia senza ricorrere agli strumenti è sempre stato di grande aiuto, specialmente se sto mantenendo il codice.

Personalmente, penso che ci sia spazio per entrambi gli strumenti e il registro in-codice.

So che Git non fa questo e la semplice risposta è "perché sulla terra sarebbe andare lì? "

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

Ogni utente di un file deve prima elaborarlo tramite il sistema di controllo della versione. Questo è un accoppiamento stretto, ad es. il tuo IDE preferito si interromperà se non supporta il tuo VCS.

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

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

Se utilizzi il software di monitoraggio delle versioni ( Git , SVN , ecc.), quindi dovresti includere tali note nei tuoi messaggi di commit. Nessuno vuole scavare attraverso le intestazioni di ogni file di codice per generare note di rilascio o vedere una panoramica di quali modifiche sono state apportate. Questi registri delle modifiche devono essere archiviati insieme, nella cronologia di monitoraggio della versione, nel tracker dei difetti o in entrambi.

Se stai cercando una buona lettura su questo argomento, ti consiglio il quarto capitolo di Pulisci codice .

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 dove diversi membri del team stanno potenzialmente lavorando nelle stesse aree di codice, inserire un breve commento di revisione nell'ambito corretto (metodo o classe) che indica che è stata apportata una modifica può essere molto utile per risolvere rapidamente conflitti di unione o di controllo.

Allo stesso modo, quando si lavora in un ambiente in cui sono coinvolte diverse sezioni (caratteristiche), è più facile per una terza persona (build master) identificare cosa fare per risolvere potenziali conflitti.

Ogni volta che devi allontanarti dall'IDE e chiedere a qualcuno perché ha cambiato qualcosa, è un disturbo per la produttività di entrambi i membri del team. Una nota rapida nell'ottica corretta può aiutare ad eliminare o eliminare la maggior parte di questa interruzione.

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

In passato era normale aggiungere informazioni nel riepilogo delle funzioni quando dovevamo affidarci a strumenti esterni (ad esempio javadocs) per creare note di rilascio dal codice. È in gran parte inutile o ridondante con i moderni strumenti di controllo delle versioni.

Potrebbe avere senso solo come commento in un pezzo di codice molto modulare, se si deve ricorrere a qualche codice oscuro o non stellare che i futuri sviluppatori sarebbero tentati di cambiare - inconsapevole del motivo alla base - come in un soluzione alternativa a un errore / mancanza della libreria.

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

Ci sono tuttavia alcuni casi in cui i riferimenti nel sistema di ticket e / o altra documentazione hanno senso. Ad esempio, se c'è una lunga spiegazione del disegno o una descrizione delle alternative. O informazioni su come testare le cose o spiegazioni sul perché è stato fatto esattamente in quel modo. Se è breve, appartiene al file stesso; se è lungo e / o si tratta di un'immagine più grande, probabilmente vorrai metterlo da qualche altra parte e farne riferimento.

Il progetto al quale sono attualmente assegnato al lavoro aveva questo tipo di elenco di numeri di bug all'inizio di ogni file; tuttavia, nessuno degli sviluppatori ancora sul progetto si aggiunge ad esso. La maggior parte di loro pensa che sia uno spreco inutile di spazio, in quanto è di gran lunga inferiore al monitoraggio dei bug in un file utilizzando il nostro sistema di controllo delle versioni.

In alcuni file critici che sono stati sottoposti a molte correzioni e miglioramenti, questi elenchi sono diventati così grandi che devi scorrere oltre per ottenere il codice. Quando greping questi elenchi può causare diversi falsi positivi come un breve titolo del bug o una breve descrizione è elencata con ciascuno.

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