Di solito considero tali commenti una cattiva pratica e penso che questo tipo di informazioni appartenga ai registri di commit di SCM. Rende il codice più difficile da leggere nella maggior parte dei casi.
Tuttavia , faccio spesso qualcosa del genere per tipi specifici di modifiche.
Caso 1 - Attività
Se usi un IDE come Eclipse, Netbeans, Visual Studio (o hai qualche modo di fare ricerche di testo sulla tua base di codice con qualsiasi altra cosa), forse il tuo team usa alcuni "tag di commento" o "tag di attività" specifici. Nel qual caso questo può essere utile.
Di tanto in tanto, quando rivedo il codice, aggiungo qualcosa di simile al seguente:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
o:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
Per questo uso diversi tag di attività personalizzati che posso vedere in Eclipse nella vista attività, perché avere qualcosa nei registri di commit è una buona cosa ma non abbastanza quando hai un dirigente che ti chiede in una riunione di revisione perché il bugfix XY è stato completamente dimenticato e scivolò attraverso. Quindi su questioni urgenti o pezzi di codice davvero discutibili, questo serve come promemoria aggiuntivo (ma di solito terrò breve il commento e controllerò i registri di commit perché QUESTO è il motivo per cui il promemoria è qui, quindi non ingombrare troppo il codice tanto).
Caso 2 - Patch di lib di terze parti
Se il mio prodotto deve impacchettare un pezzo di codice di terze parti come sorgente (o libreria, ma ricostruito dal sorgente) perché per qualche motivo doveva essere patchato, documentiamo la patch in un documento separato in cui elenchiamo quei "avvertimenti" per riferimento futuro, e il codice sorgente di solito conterrà un commento simile a:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Caso 3 - Correzioni non evidenti
Questo è un po 'più controverso e più vicino a ciò che chiede il tuo senior dev.
Nel prodotto su cui lavoro al momento, a volte (sicuramente non è una cosa comune) abbiamo un commento come:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Lo facciamo solo se la correzione non è ovvia e il codice viene letto in modo anomalo. Questo può essere il caso delle stranezze del browser, ad esempio, o oscure correzioni CSS che devi implementare solo perché c'è un bug di documento in un prodotto. Quindi, in generale, lo collegheremo al nostro archivio di problemi interni, che conterrà quindi il ragionamento dettagliato dietro il bugfix e i puntatori alla documentazione del bug del prodotto esterno (diciamo, un avviso di sicurezza per un noto difetto di Internet Explorer 6, oppure qualcosa del genere).
Ma come detto, è abbastanza raro. E grazie ai tag attività, possiamo eseguirli regolarmente e verificare se queste strane correzioni hanno ancora senso o possono essere eliminate gradualmente (ad esempio, se abbiamo abbandonato il supporto per il prodotto difettoso causando in primo luogo il bug).
Questo solo in: un esempio di vita reale
In alcuni casi, è meglio di niente :)
Mi sono imbattuto in un'enorme classe di calcolo statistico nella mia base di codice, in cui il commento dell'intestazione era sotto forma di un log delle modifiche con il solito yadda yadda: revisore, data, ID bug.
All'inizio ho pensato di scartare, ma ho notato che gli ID dei bug non solo non corrispondevano alla convenzione del nostro attuale tracker dei problemi, ma non corrispondevano nemmeno a quelli del tracker usato prima che mi unissi alla compagnia. Quindi ho cercato di leggere il codice e capire cosa stava facendo la classe (non essendo uno statistico) e ho anche cercato di scoprire questi rapporti sui difetti. Di fatto erano abbastanza importanti e avrebbero modificato la vita del prossimo ragazzo per modificare il file senza conoscerli abbastanza orribilmente, dato che si trattava di problemi di precisione minori e casi speciali basati su requisiti molto specifici emessi dal cliente originario di allora . In conclusione, se questi non fossero stati lì, non lo avrei saputo. Se non fossero stati lì dentro E avessi avuto una migliore comprensione della classe,
A volte è difficile tenere traccia di requisiti molto vecchi come questi. Alla fine quello che ho fatto è stato comunque rimuovere l'intestazione, ma dopo aver nascosto un commento a blocchi prima di ogni funzione incriminante che descriveva il motivo per cui questi "strani" calcoli sono richieste specifiche.
Quindi in quel caso li consideravo ancora una cattiva pratica, ma ragazzo ero contento che lo sviluppatore originale li avesse almeno messi dentro! Sarebbe stato meglio invece commentare chiaramente il codice, ma credo che fosse meglio di niente.