Dicas de nomenclatura e estilo de código para scripts C# no Unity

Você não pode definir variáveis com espaços no nome porque C# usa o caractere de espaço para separar identificadores. Esquemas de capitalização podem aliviar o problema de ter que usar nomes compostos ou frases no código-fonte.

Listados abaixo estão várias convenções de nomenclatura e capitalização bem conhecidas:

Case camel

Também conhecido como camel caps, case camel é a prática de escrever frases sem espaços ou pontuação, separando palavras com uma única letra maiúscula. A primeira letra é minúscula.

Normalmente, variáveis locais e parâmetros de método aparecem em case camel. Por exemplo:

examplePlayerController
maxHealthPoints
endOfFile

Case Pascal

Case Pascal é uma variação do case camel, onde a letra inicial é maiúscula. Use isso para nomes de classes e métodos no desenvolvimento Unity. Campos públicos também podem ser em case Pascal. Por exemplo:

ExamplePlayerController
MaxHealthPoints
EndOfFile

Case Snake

Neste caso, os espaços entre as palavras são substituídos por um caractere de sublinhado. Por exemplo:

example_player_controller
max_health_points
end_of_file

Case kebab

Aqui, os espaços entre as palavras são substituídos por traços. As palavras então aparecem em uma espécie de "espeto" de caracteres de traço. Por exemplo:

exemplo-controle-jogador
max-pontos-de-vida
fim-do-arquivo

O problema com o case kebab é que muitas linguagens de programação usam o traço como sinal de menos. Além disso, algumas linguagens interpretam números separados por traços como datas do calendário.

Notação húngara

O nome da variável ou função geralmente indica sua intenção ou tipo. Por exemplo:

int iContador
string strNomeDoJogador

A notação húngara é uma convenção mais antiga e não é comumente usada no desenvolvimento em Unity.

Considere estas regras para suas variáveis e campos:

• Use substantivos para nomes de variáveis: Os nomes das variáveis devem ser claros e descritivos porque representam uma coisa ou estado específico. Use um substantivo ao nomeá-las, exceto quando a variável for do tipo bool (veja abaixo).
• Prefixe Booleans com um verbo: Essas variáveis indicam um valor verdadeiro ou falso. Frequentemente, eles são a resposta para uma pergunta, como: O jogador está correndo? O jogo acabou?
• Prefixe-os com um verbo para tornar seu significado mais aparente. Frequentemente, isso é combinado com uma descrição ou condição, por exemplo, isDead, isWalking, hasDamageMultiplier, etc.
• Use nomes significativos. Não abrevie (a menos que seja matemática): Os nomes das suas variáveis revelarão sua intenção. Escolha nomes que sejam fáceis de pronunciar e pesquisar.
• Embora variáveis de uma letra sejam adequadas para loops e expressões matemáticas, não abrevie em outras situações. Clareza é mais importante do que qualquer tempo economizado ao omitir algumas vogais.
• Para protótipos rápidos, você pode usar nomes curtos "lixo" temporariamente e depois refatorar para nomes mais significativos mais tarde.
• Use a notação Pascal para campos públicos e use a notação camel para variáveis privadas: Como alternativa aos campos públicos, use propriedades com um "getter" público (veja as seções anteriores e seguintes).
• Evite muitos prefixos ou codificação especial: Você pode prefixar variáveis de membro privadas com um sublinhado (_) para diferenciá-las de variáveis locais.
• Alternativamente, use a palavra-chave this para distinguir entre variáveis de membro e locais no contexto e pule o prefixo. Campos e propriedades públicas geralmente não têm prefixos.
• Alguns guias de estilo usam prefixos para variáveis de membro privadas (m_), constantes (k_) ou variáveis estáticas (s_), para que o nome possa revelar mais sobre a variável à primeira vista.
• Muitos desenvolvedores evitam isso e confiam no Editor em vez disso. No entanto, nem todos os IDEs suportam destaque e codificação de cores, e algumas ferramentas não conseguem mostrar contexto rico de forma alguma. Considere isso ao decidir como (ou se) você aplicará prefixos em equipe.
• Especifique (ou omita) modificadores de nível de acesso de forma consistente: Se você omitir o modificador de acesso, o compilador assumirá que o nível de acesso deve ser privado. Isso funciona bem, mas seja consistente em como você omite o modificador de acesso padrão.
• Lembre-se de que você precisará usar protegido se quiser isso em uma subclasse mais tarde.

Enums são tipos de valor especiais definidos por um conjunto de constantes nomeadas. Por padrão, as constantes são inteiros, contando a partir de zero.

Use a notação Pascal para nomes e valores de enum. Você pode colocar enums públicos fora de uma classe para torná-los globais. Use um substantivo singular para o nome do enum.

Observação: Enums bitwise marcados com a System.FlagsAttribute são a exceção a esta regra. Você normalmente os pluraliza, pois representam mais de um tipo.

Siga estas regras padrão ao nomear suas classes e interfaces:

Use substantivos em notação Pascal para nomes de classes: Isso manterá suas classes organizadas.

Se você tiver um MonoBehaviour em um arquivo, o nome do arquivo de origem deve corresponder: Você pode ter outras classes internas no arquivo, mas apenas um MonoBehaviour deve existir por arquivo.

Prefixe os nomes das interfaces com um "I" maiúsculo: Siga isso com um adjetivo que descreva a funcionalidade.

Em C#, cada instrução executada é realizada no contexto de um método.

Os métodos realizam ações, então aplique essas regras para nomeá-los adequadamente:

Comece o nome com um verbo: Adicione contexto se necessário (por exemplo, ObterDireção, EncontrarAlvo, etc.)

Use camel case para parâmetros: Formate os parâmetros passados para o método como variáveis locais.

Métodos que retornam bool devem fazer perguntas: Assim como as variáveis Booleanas, prefixe os métodos com um verbo se eles retornarem uma condição verdadeira-falsa. Isso os formula na forma de uma pergunta (por exemplo, OJogoTerminou, ComeçouTurno).

Observação: Os termos “função” e “método” são frequentemente usados de forma intercambiável no desenvolvimento Unity. No entanto, como você não pode escrever uma função sem incorporá-la em uma classe em C#, “método” é o termo correto.

Eventos em C# implementam o padrão observador. Esse padrão de design de software define uma relação na qual um objeto, o sujeito (ou publicador), pode notificar uma lista de objetos dependentes chamados observadores (ou assinantes). Assim, o sujeito pode transmitir mudanças de estado para seus observadores sem acoplar fortemente os objetos envolvidos.

Vários esquemas de nomenclatura existem para eventos e seus métodos relacionados no sujeito e observadores. Experimente as práticas nas seções a seguir.

Nomeie o evento com uma frase verbal. Certifique-se de escolher uma que comunique a mudança de estado com precisão.

Use o presente ou o particípio passado para indicar o estado dos eventos como antes ou depois. Por exemplo, especifique “AbrindoPorta” para um evento antes de abrir uma porta e “PortaAberta” para um evento depois.

Use o delegado System.Action para eventos. Na maioria dos casos, o delegado Action pode lidar com os eventos necessários para a jogabilidade.

Você pode passar até 16 parâmetros de entrada de diferentes tipos com um tipo de retorno void. Usar o delegado pré-definido economiza código.

Observação: Você também pode usar os delegados EventHandler ou EventHandler. Concorde como uma equipe sobre como todos devem implementar eventos.

Prefixe o método que gera o evento (no sujeito) com “On.” O sujeito que invoca o evento normalmente o faz a partir de um método prefixado com “On” (por exemplo, “OnOpeningDoor” ou “OnDoorOpened”).

Prefixe o método de manipulação de eventos (no observador) com o nome do sujeito e um sublinhado (_). Se o sujeito se chama “GameEvents,” seus observadores podem ter um método chamado “GameEvents_OpeningDoor” ou “GameEvents_DoorOpened.”

Decida um esquema de nomenclatura consistente para sua equipe e implemente essas regras em seu guia de estilo.

Observação: Este “método de manipulação de eventos” não deve ser confundido com o delegado EventHandler.

Crie EventArgs personalizados apenas se necessário. Se você precisar passar dados personalizados para seu Evento, crie um novo tipo de EventArgs, seja herdado de System.EventArgs ou de uma struct personalizada.

Use namespaces para garantir que suas classes, interfaces, enums, etc. não entrem em conflito com aquelas já existentes de outros namespaces, ou do Namespace Global. Namespaces também podem evitar conflitos com ativos de terceiros da Unity Asset Store ou outras cenas de teste que não farão parte da versão final do projeto.

Ao aplicar namespaces:

Use a notação Pascal sem símbolos especiais ou sublinhados.

Adicione uma diretiva using no topo do arquivo para evitar digitação repetida do prefixo do namespace.

Crie sub-namespaces também. Use o operador ponto (.) para delimitar os níveis de nome, permitindo que você organize seus scripts em categorias hierárquicas. Por exemplo, você pode criar “MyApplication.GameFlow”, “MyApplication.AI”, “MyApplication.UI” e assim por diante, para conter diferentes componentes lógicos do seu jogo.

No código, essas classes são referidas como Enemy.Controller1 e Enemy.Controller2, respectivamente. Adicione uma linha using para economizar digitação do prefixo (por exemplo, using Enemy;).

Quando o compilador encontra os nomes das classes Controller1 e Controller2, ele entende que você quer dizer Enemy.Controller1 e Enemy.Controller2.

Se o script precisar se referir a classes com o mesmo nome de diferentes namespaces, use o prefixo para diferenciá-las. Por exemplo, se você tiver uma classe Controller1 e Controller2 no namespace Player, você pode escrever Player.Controller1 e Player.Controller2 para evitar conflitos. Caso contrário, o compilador relatará um erro.