Al di fuori del mondo di Visual Studio, in cui gli sviluppatori si aspettano che tutto avvenga in modo automatico, grep di codice sorgente è una pratica normale e funziona davvero molto bene.
Il problema con gli strumenti di refactoring di Visual Studio è che danno un falso senso di sicurezza facendoti sentire al sicuro quando si modifica il codice, mentre si possono facilmente introdurre regressioni in qualsiasi parte di codice, ma semplice. Anche in linguaggi come C #, ci sono almeno due cose molto popolari che si avvitano con il refactoring automatico: Reflection e dynamic . Dovrei dire cosa succede quando ti fidi di uno strumento per fare un semplice rinominare in una lingua come JavaScript?
Allo stesso tempo, grep e un po 'di esplorazione del codice difficilmente saranno ingannati da Reflection o dynamic . Poiché grep restituisce a malapena le occorrenze di una determinata stringa, non interessa se questa stringa rappresenta un nome di una variabile o si verifica in una stringa o in un commento. Spetta a te, come sviluppatore, determinare se un'occorrenza si riferisce effettivamente alla variabile che stai attualmente rinominando, o qualcosa di diverso. Il codice pulito con nomi di variabili ben scelti aiuta moltissimo.
Torna a Visual Studio, lo strumento rinomina non è limitato al codice. Puoi usarlo come pure un intelligente grep , che non solo conosce la struttura del tuo codice, ma cerca anche all'interno di stringhe e commenti, e solo quello; se stai rinominando Cost class in Price , non vuoi rinominare Costs nel tuo codice, quindi limitare la ricerca a stringhe e commenti è in realtà molto intelligente:
Rename can be used to change the names in comments and in strings and to change the declarations and calls of an identifier.
Fonte: MSDN
Tutto ciò che devi fare è, durante la rinomina, per:
Select the Search in Comments check box.
Ma perché non c'è una sintassi che permetta di mettere cref nei commenti in-code? Mentre a questa domanda sarebbe meglio rispondere dagli stessi sviluppatori di Microsoft, potrei immaginare alcuni motivi:
-
La sintassi dei commenti XML, in quanto implementata per C #, è abbastanza ostile all'utente e eredita la scomodità dell'utente di XML.
Heck, anche Visual Studio non supporta la sintassi completa (ad esempio, cosa è successo a <see langword /> , che è, tra l'altro, una delle funzionalità più utilizzate, data la formulazione ufficiale dei metodi booleani "Returns < see langword=" true "/ > se qualcosa, altrimenti, < see langword=" false "/ >." o il numero di "< see langword=" null "/ >" si devono inserire metodi che prendono i tipi di riferimento per riferimento nei parametri?!)
-
Nella maggior parte dei progetti che ho visto, a nessuno interessa nemmeno cref classi e membri nei commenti XML. Coloro che effettivamente si preoccupano sono quelli che sviluppano le librerie e le strutture che dovrebbero essere riutilizzate e dovrebbero avere una documentazione generata automaticamente.
L'obiettivo principale dei commenti XML, dopo tutto, non è quello di rendere i commenti più facili da usare, ma di (1) generare documentazione e (2) fornire magicamente documentazione senza soluzione di continuità all'interno di Visual Studio tramite tooltip.
I commenti nel codice, tuttavia, non vengono mai usati in questo modo. Pertanto, l'incentivo a dedicare tempo alla scrittura dei tag XML diventa estremamente basso.
-
Il riferimento alle classi pubbliche e ai membri all'interno del metodo non avviene quotidianamente. Mentre i commenti XML sono documentazione pubblica, e il riferimento incrociato è uno strumento particolarmente prezioso, i commenti in codice stanno appena spiegando qualcosa sul codice che non è chiaro per il lettore. Pertanto, la maggior parte dei commenti si limiterà piuttosto a spiegare l'algoritmo stesso (o l'hack), nell'ambito del metodo stesso.
A volte, il commento all'interno del metodo, tuttavia, parla di membri della classe come questo:
// While walking through the sequence, it should be necessary to prevent the
// caller from removing elements of the sequence when 'Cleanup' is being
// called. Therefore, before the loop starts, I set 'this.lockSequence' to
// 'true', while 'Cleanup' checks this variable before doing its job.
Tuttavia, spiegando la scarsa implementazione di un meccanismo di blocco, il commento non si riferisce al membro pubblico della classe, ma a private bool lockSequence ; questo ha senso qui, ma creerebbe un'incoerenza con la documentazione XML che non può fare riferimento a membri privati.
