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

13 minutos

Neste exercício, você adicionará notas ao seu código e desativará temporariamente certas linhas de código da compilação. Em seguida, você verá como o compilador C# entende o espaço em branco e como usar o 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 depois dos símbolos de comentário de código na linha atual.

// This is a code comment!

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

Quando quiser deixar uma observação sobre a intenção de uma passagem de código. Pode ser útil incluir comentários de código que descrevam o propósito ou o processo de pensamento quando você estiver escrevendo um conjunto particularmente desafiador de instruções de codificação. Mais tarde, irá agradecer por ter feito isso.
Quando quer remover temporariamente o código da aplicação para tentar uma abordagem diferente, mas ainda não está convencido de que a nova ideia funcionará. Pode comentar o código, escrever o novo código e, quando estiver satisfeito, o novo código funcionará da maneira pretendida, pode eliminar com segurança o antigo (código comentado).
Adicione uma mensagem como TODO para lembrar de examinar uma determinada passagem de código posteriormente. Embora você deva usar isso criteriosamente, é uma abordagem útil. Pode estar a trabalhar noutra funcionalidade quando lê uma linha de código que origina uma preocupação. Em vez de ignorar a nova preocupação, pode marcá-la para investigação posterior.

Nota

Comentários de código devem ser usados para dizer o que o código não pode. Geralmente, os programadores atualizam o código, mas esquecem-se de atualizar os comentários do código. É melhor utilizar comentários para ideias de nível superior e não adicionar comentários sobre como funciona uma linha de código individual.

Prepare seu ambiente de codificação

Este módulo inclui exercícios que o guiam através do processo de criação e execução de código de exemplo. Você é incentivado a concluir essas atividades usando o Visual Studio Code como seu ambiente de desenvolvimento. Usar o Visual Studio Code para essas atividades ajudará você a se sentir mais confortável escrevendo e executando 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 para outro sistema operacional) para abrir o Visual Studio Code.
No menu Arquivo de código do Visual Studio, selecione Abrir pasta.
Na caixa de diálogo Abrir pasta , navegue até a pasta Área de trabalho do Windows.

Se você tiver um local de pasta diferente onde você mantém projetos de código, você pode usar esse local de pasta em vez disso. Para este treinamento, o importante é ter um local que seja fácil de localizar e lembrar.
Na caixa de diálogo Abrir pasta , selecione Selecionar pasta.

Se vir uma caixa de diálogo de segurança a perguntar se confia nos autores, selecione Sim.
No menu Terminal de código do Visual Studio, selecione Novo terminal.

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

Se você estiver trabalhando em seu próprio PC em vez de em uma área restrita ou ambiente hospedado e tiver concluído outros módulos do Microsoft Learn nesta série C#, talvez já tenha criado uma pasta de projeto para exemplos de código. Se esse for o caso, você pode pular a próxima etapa, que é usada para criar um aplicativo de console na pasta TestProject.
No prompt de comando do Terminal, para criar um novo aplicativo de console em uma pasta especificada, digite o seguinte prompt:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Este comando .NET CLI usa um modelo de programa .NET para criar um 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 seu .csproj arquivo.

Se for exibida uma mensagem informando que os arquivos já existem, continue com as próximas etapas. Você reutilizará os arquivos de projeto existentes.
Na visualização EXPLORER, expanda a pasta CsharpProjects .

Você deve ver a pasta TestProject e dois arquivos, um arquivo de programa C# chamado Program.cs e um arquivo de projeto C# chamado TestProject.csproj.
No menu Arquivo de código do Visual Studio, selecione Abrir pasta.
Na caixa de diálogo Abrir pasta , selecione a pasta CsharpProjects e, em seguida, selecione Selecionar pasta.
No modo de exibição EXPLORER, expanda a pasta TestProject e selecione Program.cs.
Exclua as linhas de código existentes.

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

Criar e usar comentários de código

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

No painel Editor de Códigos do Visual Studio, 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 rever os seus comentários e atualizações de código.

Observe que os comentários de código são usados para documentar a possível alteração que está sendo feita e para desativar temporariamente a mensagem antiga enquanto você testa a nova mensagem. O próximo passo será testar a atualização. Se você estiver satisfeito com o novo código, poderá excluir com segurança o código antigo que foi comentado. Esta é uma abordagem mais segura e metódica para modificar o código de trabalho até que você esteja convencido de que está pronto para removê-lo permanentemente.
No menu "Arquivo" do Visual Studio Code, clique em "Salvar".
Na vista EXPLORER, para abrir um Terminal na localização da pasta TestProject, clique com o botão direito do rato em TestProject e, em seguida, selecione Abrir no Terminal Integrado.
No prompt de comando do Terminal, digite dotnet run e pressione Enter.

Deverá ver o seguinte resultado:
```
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 deve corresponder ao seguinte:

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

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

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

Nota

Há muitos conceitos de C# nesta listagem de código que podem ser novos para si. Não é necessário compreender o que o código faz para entender como os comentários podem ajudar os leitores a compreender a finalidade do código.

Reserve um minuto para ver se você consegue descobrir o propósito do código.

Considerando os comentários, poderá descobrir o que o código faz (supondo que os comentários descrevem precisamente o estado atual e que foram atualizados conforme o código foi atualizado). Mas será que consegue saber por que existe este código? Não seria útil se houvesse alguma explicação na parte superior do arquivo de código que fornecesse algum contexto e descrevesse seu propósito?
Considere como você melhoraria os comentários.

Observe que há dois problemas principais com esses comentários:
- Os comentários de código explicam desnecessariamente a funcionalidade óbvia de linhas individuais de código. São considerados comentários de baixa qualidade porque apenas explicam como o C# ou os métodos da biblioteca de classes .NET funcionam. Se o leitor não estiver familiarizado com essas ideias, ele pode procurá-las usando learn.microsoft.com ou IntelliSense.
- Os comentários de código não fornecem nenhum contexto sobre o problema que está a ser resolvido pelo código. Estes são considerados comentários de baixa qualidade porque o leitor não obtém nenhumas informações sobre a finalidade deste código, especialmente no que diz respeito à forma como se relaciona com o sistema maior.

Remova os comentários existentes.

O código deve 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 seu 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 tudo o que toca à legibilidade do código, deve utilizar o seu bom senso. Faça o que considerar ser melhor para melhorar a clareza do código.

Recapitulação

As principais conclusões deste exercício:

Utilize comentários de código para deixar anotações relevantes sobre o problema que o seu código resolve.
Não utilize comentários de código que expliquem como o C# ou a biblioteca de classes .NET funciona.
Utilize comentários de código ao tentar temporariamente soluções alternativas até que esteja pronto para confirmar a nova solução de código; nesse momento, pode eliminar o código antigo.
Nunca confie nos comentários. Podem não refletir o estado atual do código após muitas alterações e atualizações.

Comentários

Esta página foi útil?