C# Nomes e Convenções

Na aula anterior você deu nomes às suas variáveis: idade, preco, quantidade. Os nomes que você inventa no código se chamam identificadores, e o C# tem dois tipos de regra para eles. As regras da linguagem são obrigatórias: quebre uma, e o programa não compila. As convenções são combinados da comunidade C#: o programa compila sem elas, mas todo programador espera que você as siga, como espera que um texto em português comece com maiúscula. Nesta aula você aprende as duas, conhece as palavras que não podem ser nomes e o truque do @ para quando você realmente precisa de uma delas.

Os programas desta aula foram rodados na máquina fictícia da Ana com o .NET 10 SDK (C# 14), na pasta ~/cs/nomes, com dotnet run arquivo.cs. As saídas foram copiadas da tela.

A ideia: o nome na chamada da escola

Numa sala de aula, cada aluno tem um nome, e a professora chama pelo nome. Há regras que ninguém discute: o nome vai no registro do jeito que está escrito, e "Ana Clara" e "ana clara" são, para o sistema da escola, cadastros diferentes. E há costumes: o nome começa com maiúscula, o sobrenome vem depois.

No C#, é igual. Algumas regras são da linguagem (o compilador confere), outras são costumes (as pessoas conferem). E, como na escola, há nomes que já estão "ocupados": ninguém pode se chamar "Diretoria". No C#, são as palavras-chave.

1. As regras: o que um nome pode ter

Um identificador do C#:

• começa com uma letra ou com _ (sublinhado);
• depois, pode ter letras, dígitos (0 a 9) e _;
• não pode ter espaço, hífen, ponto, $, # nem outros símbolos;
• não pode ser uma palavra-chave reservada (seção 3).

int idade = 29;
int idade2 = 30;
int _contador = 0;
int precoTotal = 100;
int maçãs = 3;
Console.WriteLine($"{idade} {idade2} {_contador} {precoTotal} {maçãs}");

$ dotnet run validos.cs
29 30 0 100 3

Todos válidos. Repare no maçãs: o C# aceita letras acentuadas e outras letras do Unicode (o padrão que inclui os alfabetos do mundo inteiro). Mesmo assim, o guia usa nomes sem acento (macas, preco): nem todo teclado, editor e ferramenta lida bem com eles, e o costume da comunidade é evitar. Como o C# diferencia a de á, um acento esquecido também vira um nome diferente.

O que não pode

Um dígito no começo:

int 2lugar = 2;
Console.WriteLine(2lugar);

$ dotnet run digito.cs
/home/ana/cs/nomes/digito.cs(1,5): error CS1001: Identificador esperado
/home/ana/cs/nomes/digito.cs(1,5): error CS1003: Erro de sintaxe, "," esperado
/home/ana/cs/nomes/digito.cs(2,22): error CS1003: Erro de sintaxe, "," esperado

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.

"Identificador esperado" (Identifier expected): depois do int, o compilador esperava um nome, e encontrou o número 2. Um nome que começa com dígito seria confundido com um número. Conserto: segundoLugar ou lugar2.

Um espaço ou um hífen no meio:

$ dotnet run espaco.cs                  « int minha idade = 29;
/home/ana/cs/nomes/espaco.cs(1,11): error CS1003: Erro de sintaxe, "," esperado

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.
$ dotnet run hifen.cs                   « int preco-final = 10;
/home/ana/cs/nomes/hifen.cs(1,10): error CS1003: Erro de sintaxe, "," esperado

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.

Nos dois casos, o compilador leu o primeiro pedaço como o nome (minha, preco) e não soube o que fazer com o resto. Ele sugere uma vírgula porque int minha, idade declararia duas variáveis (aula Variáveis), mas não é o que você quer. Um espaço separa palavras; um hífen é o sinal de menos: preco-final seria "preco menos final". Conserto: junte as palavras com maiúscula, minhaIdade, precoFinal (seção 5).

E um símbolo:

$ dotnet run cifrao.cs                  « decimal preco$ = 5m;
/home/ana/cs/nomes/cifrao.cs(1,14): error CS1056: Caractere inesperado '$'

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.

Segundo lugar: 2
Idade: 29
Preço final: 10

int 2lugar = 2;
int minha idade = 29;
int preco-final = 10;
Console.WriteLine($"Segundo lugar: {2lugar}");
Console.WriteLine($"Idade: {minha idade}");
Console.WriteLine($"Preço final: {preco-final}");

int segundoLugar = 2;
int minhaIdade = 29;
int precoFinal = 10;
Console.WriteLine($"Segundo lugar: {segundoLugar}");
Console.WriteLine($"Idade: {minhaIdade}");
Console.WriteLine($"Preço final: {precoFinal}");

Repare que, dentro das aspas, Preço final pode ter acento e espaço à vontade: é texto, não nome.

2. Maiúsculas e minúsculas contam

Para o C#, idade e Idade são nomes diferentes, tão diferentes quanto idade e altura:

int idade = 29;
int Idade = 50;
Console.WriteLine($"idade = {idade}, Idade = {Idade}");

$ dotnet run maiusc.cs
idade = 29, Idade = 50

Compila, mas é uma péssima ideia: quem lê não sabe qual é qual. E o contrário, declarar com uma forma e usar com outra, é um dos erros mais comuns:

$ dotnet run caso.cs                    « int Total = 5; Console.WriteLine(total);
/home/ana/cs/nomes/caso.cs(2,19): error CS0103: O nome "total" não existe no contexto atual
/home/ana/cs/nomes/caso.cs(1,5): warning CS0219: A variável "Total" é atribuída, mas seu valor nunca é usado

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.

O erro e o aviso contam a mesma história de dois lados: total (minúsculo) não existe, e Total (maiúsculo) nunca foi usada. As convenções da seção 5 evitam essa confusão: em C#, uma variável sempre começa com minúscula.

3. Palavras-chave: os nomes ocupados

As palavras-chave (keywords) são as palavras da própria linguagem: int, if, class, return… Elas são sempre minúsculas, e os editores as pintam de outra cor. As reservadas nunca podem ser usadas como nome. Veja o que acontece quando a Ana tenta guardar a turma numa variável chamada class ("turma", em inglês):

string class = "3º A";
Console.WriteLine(class);

$ dotnet run chave.cs
/home/ana/cs/nomes/chave.cs(1,8): error CS1001: Identificador esperado
/home/ana/cs/nomes/chave.cs(1,8): error CS1002: ; esperado
/home/ana/cs/nomes/chave.cs(1,14): error CS1001: Identificador esperado
/home/ana/cs/nomes/chave.cs(1,14): error CS1514: { esperado
/home/ana/cs/nomes/chave.cs(1,14): error CS1513: } esperada
/home/ana/cs/nomes/chave.cs(1,14): error CS8803: As instruções de nível superior precisam preceder as declarações de namespace e de tipo.
/home/ana/cs/nomes/chave.cs(1,14): error CS1525: Termo de expressão inválido "="
/home/ana/cs/nomes/chave.cs(2,19): error CS1026: ) esperado
/home/ana/cs/nomes/chave.cs(2,19): error CS1002: ; esperado
/home/ana/cs/nomes/chave.cs(2,24): error CS1001: Identificador esperado
/home/ana/cs/nomes/chave.cs(2,24): error CS1514: { esperado
/home/ana/cs/nomes/chave.cs(2,24): error CS1513: } esperada
/home/ana/cs/nomes/chave.cs(2,24): error CS1022: Definição de namespace ou tipo, ou final do arquivo esperado

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.

Treze erros para duas linhas! Quando o compilador vê class, ele entende "aqui começa a declaração de uma classe" (aula Classes e Objetos) e passa a esperar o nome da classe, uma {, uma }… Nada disso está lá, e cada expectativa frustrada vira uma mensagem. O primeiro erro é o que importa: (1,8): Identificador esperado, exatamente onde está o class. Quando aparecer uma parede de erros estranhos, procure uma palavra-chave usada como nome.

As palavras reservadas

São 77, e você vai conhecer quase todas ao longo do guia. Nenhuma pode ser nome:

As palavras contextuais

Outras palavras só têm significado especial em certos lugares do código: são as contextuais. Foram acrescentadas à linguagem ao longo dos anos, e para não quebrar programas antigos que já as usavam como nome, o C# continua aceitando-as como identificadores:

int var = 3;
string record = "recorde";
int value = 10;
Console.WriteLine($"{var} {record} {value}");

$ dotnet run contextual.cs
3 recorde 10

Algumas delas: var, value, record, async, await, get, set, init, required, partial, where, yield, nameof, when, with, and, or, not, field. Compila, mas evite: um int var confunde qualquer leitor.

4. O @: uma palavra-chave como nome

Se você precisa mesmo de um nome igual a uma palavra reservada, ponha um @ na frente. O @class é o identificador class, sem o significado de palavra-chave:

string @class = "3º A";
int @int = 5;
Console.WriteLine($"Turma {@class}, sala {@int}");
Console.WriteLine(@class);

$ dotnet run arroba.cs
Turma 3º A, sala 5
3º A

O @ não faz parte do nome: ele só avisa o compilador "isto é um nome, não uma palavra-chave". Por isso @idade e idade são a mesma variável:

$ dotnet run mesmo.cs                   « int @idade = 29; Console.WriteLine(idade);
29

Quando isso é útil? Quase só quando o seu código conversa com outro sistema que já usa esse nome, por exemplo um arquivo JSON com um campo "class" (aula JSON). No seu próprio código, prefira um nome que não precise de @: turma, sala.

string class = "3º A";
Console.WriteLine($"Turma: {class}");

string turma = "3º A";
Console.WriteLine($"Turma: {turma}");

5. As convenções: camelCase e PascalCase

Nomes com várias palavras não podem ter espaço. O jeito do C# de juntá-las é com maiúsculas no começo de cada palavra. Existem dois estilos, e cada um tem o seu lugar:

É por isso que você escreve Console.WriteLine (uma classe e um método do .NET, em PascalCase) e int quantidade (uma variável, em camelCase). Olhando só para o nome, quem conhece as convenções já sabe o que ele é. Este programa usa as três primeiras (as classes são do Nível 2, mas os nomes já dá para ler):

int quantidadeCadernos = 3;                // variável: camelCase
decimal precoUnitario = 5.50m;             // variável: camelCase
Console.WriteLine(Loja.CalcularTotal(quantidadeCadernos, precoUnitario));

class Loja                                 // classe: PascalCase
{
    const int LimiteDeItens = 10;          // constante: PascalCase

    public static decimal CalcularTotal(int quantidade, decimal preco)   // método: PascalCase; parâmetros: camelCase
    {
        return quantidade * preco;
    }
}

$ dotnet run convencoes.cs
16,50

Siglas

Siglas de duas letras ficam todas maiúsculas (IO, como em System.IO); siglas maiores viram uma palavra comum (Html, Json, Xml, como em System.Text.Json). Em camelCase, a sigla do começo fica toda minúscula: htmlPagina, ioErro.

O compilador não confere convenções

Um int PrecoTotal ou um int preco_total compilam sem nenhum aviso. Quem cobra as convenções são as pessoas, as revisões de código e os editores: o VS Code e o Visual Studio podem sublinhar nomes fora do padrão (com o aviso IDE1006, quando o projeto tem regras de estilo configuradas) e oferecem o Renomear (F2), que troca um nome em todos os lugares onde ele aparece de uma vez.

6. Como escolher um bom nome

O nome é a primeira documentação do código. Um bom nome dispensa comentários (aula Comentários).

Nomes de uma letra têm o seu lugar: i num laço curto (aula for), x e y para coordenadas. Fora disso, escreva por extenso.

Português ou inglês?

Tudo o que vem do .NET está em inglês (Console, WriteLine, Length), e em empresas e projetos abertos os nomes costumam ser em inglês também, para qualquer pessoa do mundo entender. Neste guia, os nomes que você cria estão em português (preco, quantidade), para o código se ler como uma frase enquanto você aprende. Qualquer que seja a escolha, a regra de ouro é a mesma: uma língua só no mesmo programa, e sem acento.

Quando dá errado

Referência rápida

Exercícios

Missão final: o código da Ana, nas convenções

Cliente: Bia
Total: 33,00

string NOMECLIENTE = "Bia";
int qtd = 6;
decimal Preco_Unitario = 5.50m;
decimal x = qtd * Preco_Unitario;
Console.WriteLine($"Cliente: {NOMECLIENTE}");
Console.WriteLine($"Total: {x}");

string nomeCliente = "Bia";
int quantidade = 6;
decimal precoUnitario = 5.50m;
decimal valorTotal = quantidade * precoUnitario;
Console.WriteLine($"Cliente: {nomeCliente}");
Console.WriteLine($"Total: {valorTotal}");

Leia as duas versões em voz alta. A segunda conta o que o programa faz; a primeira obriga o leitor a adivinhar o que é x.

Resumo

• Um identificador é um nome que você cria. Começa com letra ou _, depois letras, dígitos e _. Sem espaço, hífen ou símbolos (CS1001, CS1003, CS1056). Acentos são aceitos, mas o guia não usa.
• Maiúsculas contam: total e Total são nomes diferentes (CS0103 quando se mistura).
• As 77 palavras-chave reservadas (class, int, if…) não podem ser nomes; as contextuais (var, value, record…) podem, mas confundem.
• @ na frente transforma uma palavra-chave em nome: @class. O @ não faz parte do nome.
• Convenções: camelCase para variáveis e parâmetros; PascalCase para classes, métodos, propriedades, constantes, namespaces e projetos; _camelCase para campos privados; I + PascalCase para interfaces. O compilador não confere; as pessoas, sim.
• Bons nomes dizem o que guardam, sem abreviações nem o tipo no nome. Uma língua só por programa.