Exercício – Criar comentários de código eficazes

13 minutos

Neste exercício, você adicionará observações ao seu código e desabilitaremos temporariamente determinadas linhas de código da compilação. Em seguida, verá como o compilador do C# compreende o espaço em branco e como usar espaço em branco para aumentar a legibilidade do seu código.

O que é um comentário de código?

Um comentário de código é uma instrução para o compilador ignorar tudo que vem após os símbolos de comentário de código na linha atual.

// This is a code comment!

Isso pode não parecer útil a princípio, mas é útil em três situações:

Quando você quer deixar uma observação sobre a intenção de uma passagem de código. Pode ser útil incluir comentários de código que descrevem a finalidade ou o processo de pensamento quando você está escrevendo um conjunto particularmente desafiador de instruções de codificação. Isso facilitará muito seu trabalho no futuro.
Quando você deseja remover temporariamente o código do aplicativo para tentar uma abordagem diferente, mas ainda não está convencido de que sua nova ideia funcionará. Você poderá comentar o código, escrever o novo código e, quando estiver convencido de que o novo código funcionará da maneira desejada, você poderá excluir o antigo (código comentado) com segurança.
Adicionar uma mensagem como TODO para lembrá-lo de examinar uma determinada passagem de código posteriormente. Embora você deva usar isso criteriosamente, esse é uma abordagem útil. Você pode estar trabalhando em outro recurso e ler uma linha de código que desperta uma preocupação. Em vez de ignorar a nova preocupação, você pode marcá-la para investigação posterior.

Observação

Os comentários de código devem ser usados para dizer o que o código não pode fazer. Muitas vezes, os desenvolvedores atualizam o código mas esquecem de atualizar os comentários. É melhor usar comentários para ideias de nível superior e não adicionar comentários sobre como uma linha de código individual funciona.

Preparar o ambiente de codificação

Este módulo inclui exercícios que o orientam no processo de compilação e execução do código de exemplo. É recomendado concluir essas atividades usando o Visual Studio Code como ambiente de desenvolvimento. Usar o Visual Studio Code nessas atividades ajudará você a se sentir mais confortável escrevendo e executando o código em um ambiente de desenvolvedor usado por profissionais em todo o mundo.

Abra o Visual Studio Code.

Você pode usar o menu Iniciar do Windows (ou recurso equivalente em outro sistema operacional) para abrir o Visual Studio Code.
No Visual Studio Code, no menu Arquivo, selecione Abrir Pasta.
Na caixa de diálogo Abrir Pasta, navegue até a pasta Área de Trabalho do Windows.

Se você mantém os projetos de código em um local de pasta diferente, use esse local. Neste treinamento, o importante é ter um local fácil de localizar e lembrar.
Na caixa de diálogo Abrir Pasta, selecione Selecionar Pasta.

Se aparecer uma caixa de diálogo de segurança perguntando se confia nos autores, selecione Sim.
No Visual Studio Code, no menu Terminal, selecione Novo Terminal.

Observe que o prompt de comando no painel Terminal exibe o caminho da pasta atual. Por exemplo:
```
C:\Users\someuser\Desktop>
```
Observação

Se você estiver trabalhando no próprio computador em vez de em uma área restrita ou em um ambiente hospedado e tiver concluído outros módulos do Microsoft Learn desta série C#, talvez já tenha criado uma pasta de projeto para exemplos de código. Se esse for o caso, você poderá ignorar a próxima etapa, que será usada para criar o aplicativo de console na pasta TestProject.
No prompt de comando Terminal, para criar o novo aplicativo de console na pasta especificada, digite dotnet new console -o ./CsharpProjects/TestProject e pressione Enter.

Este comando da CLI do .NET usa um modelo de programa .NET para criar o novo projeto de aplicativo de console C# no local da pasta especificada. O comando cria as pastas CsharpProjects e TestProject para você e usa TestProject como o nome do arquivo .csproj.
No painel EXPLORER, expanda a pasta CsharpProjects.

Você deve ver a pasta TestProject e dois arquivos: o arquivo de programa do C#, denominado Program.cs, e o arquivo de projeto do C#, denominado TestProject.csproj.
No painel EXPLORER, para exibir o arquivo de código no painel Editor, selecione Program.cs.
Exclua as linhas de código existentes.

Você usará esse projeto de console C# para criar, compilar e executar exemplos de código durante este módulo.
Feche o painel do terminal.

Criar e usar comentários de código

Nesta tarefa, você tentará criar e remover vários tipos de comentários de código.

No painel Editor do Visual Studio Code, insira o seguinte código:

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

Para modificar seu código com comentários e revisões de código, atualize seu código da seguinte maneira:

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.");

Reserve um minuto para examinar seus comentários e atualizações de código.

Observe que os comentários de código são usados para documentar a alteração em potencial que está sendo feita e para desabilitar temporariamente a mensagem antiga à medida que você testa a nova mensagem. Sua próxima etapa será testar sua atualização. Se você estiver satisfeito com o novo código, poderá excluir com segurança o código antigo que foi comentado. Essa é uma abordagem mais segura e metódica para modificar o código funcional até que esteja convencido de que você está pronto para removê-lo permanentemente.
No menu Arquivo do Visual Studio Code, clique em Salvar.
No painel EXPLORER, para abrir o Terminal no local da pasta TestProject, clique com o botão direito do mouse em TestProject e selecione Abrir no Terminal Integrado.
No prompt de comando do Terminal, digite dotnet run e pressione Enter.

A seguinte saída deve ser exibida:
```
Bob purchased 7 widgets.
```
Novamente, se você estiver satisfeito com suas atualizações, exclua o código antigo comentado.

Exclua os comentários de código.

O código deverá corresponder ao seguinte:

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

Para aplicar um comentário em bloco que comente várias linhas, atualize seu código da seguinte maneira:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Comentários em bloco são ótimos se você precisa escrever um comentário longo ou remover muitas linhas de código. Os comentários em bloco usam um /* no início do código e um */ no final. Usar um comentário em bloco é a maneira mais rápida e fácil de desabilitar três ou mais linhas de código.

Substitua seu código existente pelo seguinte:

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);
}

Observação

Há muitos conceitos de C# nessa listagem de código que podem ser novos para você. Não é necessário entender o que o código está fazendo para apreciar o modo como os comentários podem ajudar os leitores a entender a finalidade do código.

Reserve um minuto para ver se você pode descobrir a finalidade do código.

Considerando os comentários, você poderá descobrir o que o código está fazendo (supondo que os comentários descrevam com precisão o estado atual e que tenham sido atualizados junto com o código). Mas você consegue adivinhar por que esse código existe? Não seria útil se houvesse alguma explicação na parte superior do arquivo de código que fornecesse algum contexto e descrevesse sua finalidade?
Considere como você aprimoraria os comentários.

Observe que há dois problemas principais com estes comentários:
- Os comentários de código explicam desnecessariamente a funcionalidade óbvia de linhas de código individuais. Eles são considerados comentários de baixa qualidade, porque apenas explicam como o C# ou os métodos da biblioteca de classes do .NET funcionam. Se os leitores não estiverem familiarizados com essas ideias, poderão pesquisar sobre elas usando o learn.microsoft.com ou o IntelliSense.
- Os comentários de código não fornecem nenhum contexto para o problema que está sendo resolvido pelo código. Eles são considerados comentários de baixa qualidade porque o leitor não obtém nenhuma informação sobre a finalidade desse código, especialmente sobre como ele se relaciona com o sistema maior.

Remover os comentários existentes.

O código deverá corresponder ao seguinte:

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);
}

Observe que o código já está menos confuso.

Para adicionar um comentário que explique a finalidade de nível superior do código, atualize o código da seguinte maneira:

/*
  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);
}

A utilidade de um comentário é subjetiva. Em todos os assuntos relacionados à legibilidade do código, você deverá usar o bom senso. Faça aquilo que considerar ser o melhor para aumentar a clareza do código.

Recapitulação

Os principais aprendizados deste exercício:

Use comentários de código a fim de deixar observações significativas para si mesmo sobre os problemas que cada trecho de código específico resolve.
Não use os comentários de código para explicar como funciona o C# ou a biblioteca de classes do .NET.
Use comentários de código ao experimentar temporariamente soluções alternativas até que você esteja pronto para confirmar a nova solução de código; nesse ponto, você poderá excluir o código antigo.
Nunca confie em comentários. Eles podem não refletir o estado atual do código após muitas alterações e atualizações.

Continuar

Exercício – Criar comentários de código eficazes

O que é um comentário de código?

Preparar o ambiente de codificação

Criar e usar comentários de código

Recapitulação

Comentários