Esercizio - Creare commenti di codice efficaci

13 minuti

In questo esercizio si aggiungeranno alcune note al codice e si disabiliterà temporaneamente la compilazione di alcune righe di codice, quindi si osserverà come il compilatore C# interpreta lo spazio vuoto e come usare lo spazio vuoto per migliorare la leggibilità del codice.

Che cos'è un commento di codice?

Un commento di codice è un'istruzione che indica al compilatore di ignorare tutto ciò che segue i simboli di commento del codice nella riga corrente.

// This is a code comment!

L'utilità di tutto questo potrebbe non essere immediatamente evidente, ma lo è in tre situazioni:

Quando si vuole lasciare una nota sulla finalità di un passaggio del codice, Può essere utile includere commenti al codice che descrivano lo scopo o il processo elaborato quando si scrive un set di istruzioni di codifica particolarmente complesso, che potrebbe essere difficile da ricordare in futuro.
Quando si vuole rimuovere temporaneamente il codice dall'applicazione per provare un approccio diverso, che non si è ancora certi che possa funzionare. È possibile impostare il codice come commento, scrivere il nuovo codice e, quando si è certi che il nuovo codice funzionerà come desiderato, è possibile eliminare tranquillamente il vecchio codice (commentato).
Aggiunta di un messaggio, ad esempio TODO, per ricordarsi di esaminare un determinato passaggio di codice in un secondo momento. Anche se questa è un'operazione da eseguire con cautela, è un approccio utile. Mentre si lavora a un'altra funzionalità, ci si potrebbe imbattere in una riga di codice che suscita preoccupazione. Invece di ignorarla, è possibile contrassegnarla per esaminarla in seguito.

Nota

I commenti di codice devono essere usati per indicare ciò che non può essere indicato dal codice. Spesso gli sviluppatori aggiornano il codice, ma dimenticano di aggiornare i commenti del codice. È meglio usare i commenti per concetti più generici e non per aggiungere commenti sul funzionamento di una singola riga di codice.

Preparare l'ambiente di scrittura del codice

Questo modulo include esercizi che guidano l'utente attraverso il processo di compilazione ed esecuzione di un codice di esempio. È consigliabile completare queste attività usando Visual Studio Code come ambiente di sviluppo. L'uso di Visual Studio Code per queste attività consente di acquisire familiarità nella scrittura e nell'esecuzione del codice in un ambiente di sviluppo usato da professionisti di tutto il mondo.

Aprire Visual Studio Code.

Per aprire Visual Studio Code, è possibile usare il menu Start di Windows (o una risorsa equivalente per un altro sistema operativo).
Scegliere Apri cartella dal menu File di Visual Studio Code.
Nella finestra di dialogo Apri cartella passare alla cartella Desktop di Windows.

Se si dispone di un percorso di cartella in cui si conservano i progetti di codice, è possibile usare tale percorso. Per questo training, è importante che il percorso sia facile da individuare e da ricordare.
Nella finestra di dialogo Apri cartellaselezionare Seleziona cartella.

Se viene visualizzata una finestra di dialogo di sicurezza che chiede se si considera attendibile gli autori, selezionare Sì.
Nel menu Terminale di Visual Studio Code selezionare Nuovo terminale.

Si noti che un prompt dei comandi nel pannello Terminale visualizza il percorso della cartella corrente. Ad esempio:
```
C:\Users\someuser\Desktop>
```
Nota

Se si usa il proprio PC anziché un ambiente sandbox o ospitato e sono stati completati altri moduli di Microsoft Learn in questa serie C#, potrebbe essere già stata creata una cartella di progetto per gli esempi di codice. In tal caso, è possibile ignorare il passaggio successivo, usato per creare un'app console nella cartella TestProject.
Al prompt dei comandi del terminale, per creare una nuova applicazione console in una cartella specificata, immettere il prompt seguente:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Questo comando dell'interfaccia della riga di comando .NET usa un modello di programma .NET per creare un nuovo progetto di applicazione console C# nel percorso della cartella specificato. Il comando crea le cartelle CsharpProjects e TestProject e usa TestProject come nome del file .csproj.

Se viene visualizzato un messaggio che indica che i file esistono già, continuare con i passaggi successivi. I file di progetto esistenti verranno riutilizzati.
Nella visualizzazione EXPLORER espandere la cartella CsharpProjects .

Verranno visualizzati la cartella TestProject e due file, un file di programma C# denominato Program.cs e un file di progetto C# denominato TestProject.csproj.
Scegliere Apri cartella dal menu File di Visual Studio Code.
Nella finestra di dialogo Apri cartella selezionare la cartella CsharpProjects e quindi selezionare Seleziona cartella.
Nella visualizzazione EXPLORER espandere la cartella TestProject e quindi selezionare Program.cs.
Eliminare le righe di codice esistenti.

Questo progetto console C# verrà usato per creare, compilare ed eseguire esempi di codice durante questo modulo.
Chiudere il pannello Terminale.

Creare e usare commenti di codice

In questa attività verranno creati e rimossi vari tipi di commenti di codice.

Nel pannello Editor di Visual Studio Code immettere il codice seguente:

string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

Per modificare il codice con commenti e revisioni del codice, aggiornare il codice come indicato di seguito:

string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Esaminare i commenti e gli aggiornamenti del codice.

Si noti che i commenti del codice vengono usati per documentare le potenziali modifiche in atto e per disabilitare temporaneamente il vecchio messaggio durante il test del nuovo messaggio. Il passaggio successivo sarà quello di testare l'aggiornamento. Se si è soddisfatti del nuovo codice, è possibile eliminare tranquillamente quello vecchio impostato come commento. Si tratta di un approccio più sicuro e metodico per modificare il codice funzionante, finché non si è certi di volerlo rimuovere definitivamente.
Scegliere Salva dal menu File di Visual Studio Code.
Nella visualizzazione EXPLORER, per aprire un terminale nel percorso della cartella TestProject, fare clic con il pulsante destro del mouse su TestProject e quindi scegliere Apri nel terminale integrato.
Al prompt dei comandi del terminale digitare dotnet run e quindi premere INVIO.

Verrà visualizzato l'output seguente:
```
Bob purchased 7 widgets.
```
Anche in questo caso, se si è soddisfatti degli aggiornamenti, eliminare il codice precedente che è stato commentato.

Eliminare i commenti del codice.

Il codice dovrebbe corrispondere al seguente:

string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Per applicare un commento a blocchi che commenta più righe, aggiornare il codice come indicato di seguito:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
I commenti a blocchi sono ideali se è necessario scrivere un commento lungo o rimuovere molte righe di codice. I commenti a blocchi usano un oggetto /* all'inizio del codice e un oggetto */ alla fine. Usare un commento a blocchi è il modo più rapido e semplice per disabilitare tre o più righe di codice.

Sostituire il codice esistente con quello seguente:

Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Nota

In questo listato di codice sono presenti diversi concetti di C# che potrebbero risultare nuovi. Non è necessario conoscere le operazioni eseguite dal codice per apprezzare il fatto che i commenti consentono a chi legge di capire lo scopo del codice.

Vedere se si riesce a capire lo scopo del codice.

Grazie ai commenti, è possibile capire quali operazioni vengono eseguite dal codice (presupponendo che i commenti descrivano in modo accurato lo stato corrente e siano stati aggiornati contemporaneamente al codice). Ma è possibile capire perché questo codice esiste? Non sarebbe utile se all'inizio del file di codice ci fosse una spiegazione che fornisse un contesto e ne descrivesse lo scopo?
Si consideri come migliorare i commenti.

Si noti che esistono due problemi principali con questi commenti:
- I commenti del codice spiegano inutilmente l'ovvia funzionalità delle singole righe di codice. Questi commenti sono considerati di scarsa qualità perché spiegano semplicemente come funziona C# o i metodi della libreria di classi .NET. Se chi legge non ha familiarità con questi concetti, può cercarli tramite learn.microsoft.com o IntelliSense.
- I commenti del codice non forniscono alcun contesto al problema che viene risolto dal codice. Questi commenti sono considerati di scarsa qualità perché chi legge non acquisisce alcuna informazione dettagliata sullo scopo del codice, soprattutto se correlato all'ambito più generale.

Rimuovere i commenti esistenti.

Il codice dovrebbe corrispondere al seguente:

Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Si noti che il codice è già più lineare.

Per aggiungere un commento che spieghi lo scopo più generale del codice, aggiornare il codice come indicato di seguito:

/*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

L'utilità di un commento è soggettiva. Per tutto ciò che riguarda la leggibilità del codice, è consigliabile affidarsi al buon senso e procedere nel modo che si ritiene più opportuno per migliorare la chiarezza del codice.

Riepilogo

Ecco le principali lezioni apprese da questo esercizio:

Usare i commenti di codice per inserire note significative sul problema risolto dal codice.
Non usare commenti di codice che spiegano il funzionamento di C# o della libreria di classi .NET.
Usare i commenti di codice quando si provano temporaneamente soluzioni alternative. Quando si è pronti a eseguire il commit della soluzione del nuovo codice, sarà possibile eliminare il vecchio codice.
Non considerare mai attendibili i commenti perché è possibile che non riflettano lo stato corrente del codice dopo molte modifiche e aggiornamenti.

Commenti e suggerimenti

Questa pagina è stata utile?