Práticas recomendadas de formatação para scripts C# no Unity

Juntamente com a nomenclatura, a formatação ajuda a reduzir suposições e melhora a clareza do código. Ao seguir um guia de estilo padronizado, as revisões de código se tornam menos sobre como o código se parece e mais sobre o que ele faz.

Busque personalizar a maneira como sua equipe formatará o código. Considere cada uma das seguintes sugestões de formatação de código ao configurar seu guia de estilo Unity. Você pode optar por omitir, expandir ou modificar essas regras de exemplo para atender às necessidades da sua equipe.

Em todos os casos, reflita sobre como sua equipe implementará cada regra de formatação e, em seguida, faça com que todos a apliquem de forma uniforme. Volte ao guia de estilo da sua equipe para resolver quaisquer discrepâncias. Quanto menos você pensar sobre formatação, mais produtivamente – e criativamente – você pode trabalhar.

Vamos dar uma olhada em algumas diretrizes de formatação.

Uma propriedade fornece um mecanismo flexível para ler, escrever ou calcular valores de classe. As propriedades se comportam como se fossem variáveis de membro públicas, mas na verdade são métodos especiais chamados acessores.

Cada propriedade tem um método get e set para acessar um campo privado, chamado de campo de apoio. Dessa forma, a propriedade encapsula os dados, ocultando-os de alterações indesejadas pelo usuário ou objetos externos. O “getter” e o “setter” têm seu próprio modificador de acesso, permitindo que sua propriedade seja leitura-escrita, somente leitura ou somente escrita.

Você também pode usar os acessores para validar ou converter os dados (por exemplo, para verificar se os dados se encaixam no formato preferido ou mudam um valor para uma unidade específica).

A sintaxe para propriedades pode variar, então seu guia de estilo deve definir como formatá-las. Veja os seguintes exemplos para dicas sobre como manter as propriedades consistentes em seu código.

Use propriedades com corpo de expressão para propriedades de uma linha, somente leitura (=>): Isso retorna o campo de apoio privado.

Tudo o mais usa a sintaxe de corpo de expressão { get; set; }: Se você apenas quiser expor uma propriedade pública sem especificar um campo de apoio, use a propriedade auto-implementada.

Aplique a sintaxe de corpo de expressão para os acessores set e get. Lembre-se de tornar o “setter” privado se você não quiser fornecer acesso de escrita. Alinhe o fechamento com a chave de abertura para blocos de código multilinha.

A serialização de script é o processo automático de transformar estruturas de dados ou estados de objeto em um formato que o Unity pode armazenar e reconstruir mais tarde. Por razões de desempenho, o Unity lida com a serialização de forma diferente de outros ambientes de programação.

Os campos serializados aparecem no Inspector, mas você não pode serializar campos estáticos, constantes ou somente leitura. Eles devem ser públicos ou marcados com o atributo [SerializeField]. O Unity só serializa certos tipos de campo, então consulte a documentação para o conjunto completo de regras de serialização.

Observe estas diretrizes básicas ao trabalhar com campos serializados:

Use o atributo [SerializeField]: O atributo SerializeField pode funcionar com variáveis privadas ou protegidas para fazê-las aparecer no Inspector. Isso encapsula os dados melhor do que marcar a variável como pública e impede que um objeto externo sobrescreva seus valores.

Use o atributo Range para definir valores mínimos e máximos: O atributo [Range(min, max)] é útil se você quiser limitar o que o usuário pode atribuir a um campo numérico. Ele também representa convenientemente o campo como um controle deslizante no Inspector.

Agrupe dados em classes ou estruturas serializáveis para limpar o Inspector: Defina uma classe ou estrutura pública e marque-a com o atributo [Serializable]. Defina variáveis públicas para cada tipo que você deseja expor no Inspector.

Referencie esta classe serializável de outra classe. As variáveis resultantes aparecem dentro de unidades colapsáveis no Inspector.

Existem dois estilos de indentação comuns em C#:

O estilo Allman, também conhecido como estilo BSD (do BSD Unix), coloca as chaves de abertura em uma nova linha.

O estilo K&R, ou "o verdadeiro estilo de chaves", mantém a chave de abertura na mesma linha que o cabeçalho anterior.

Existem variações sobre esses estilos de indentação também. Os exemplos deste guia usam o estilo Allman das diretrizes de design do framework Microsoft. Independentemente de qual você escolher como equipe, certifique-se de que todos sigam o mesmo estilo de indentação e chaves. Você também pode tentar as dicas nas seções a seguir.

A indentação é tipicamente de dois ou quatro espaços. Faça com que todos na sua equipe concordem com uma configuração nas preferências do seu Editor sem acender uma guerra de chaves versus espaços.

No Visual Studio para Windows, navegue até Ferramentas > Opções > Editor de Texto > C# > Tabs.

No Visual Studio para Mac, navegue até Preferências > Código Fonte > Código Fonte C#. Selecione o Estilo de Texto para ajustar as configurações.

Nota: O Visual Studio oferece a opção de converter tabs em espaços.

Não omita chaves – nem mesmo para declarações de uma linha. As chaves aumentam a consistência, o que torna seu código mais fácil de ler e manter. Neste exemplo, as chaves separam claramente a ação, DoSomething, do loop.

Se você precisar adicionar uma linha de Debug ou executar DoSomethingElse mais tarde, as chaves já estarão no lugar. Manter a cláusula em uma linha separada permite que você simplesmente adicione um ponto de interrupção.

Não remova chaves de declarações multilinha aninhadas. Remover chaves neste caso não gerará um erro, mas provavelmente causará confusão. Aplique chaves para clareza, mesmo que sejam opcionais.

A formatação pode variar, então documente as preferências da sua equipe em seu guia de estilo e padronize suas instruções de troca de acordo.

Aqui está um exemplo de indentação das instruções de caso.

Algo tão simples quanto o espaçamento pode melhorar a aparência do seu código na tela. Embora as preferências de formatação pessoal possam variar, considere as sugestões abaixo para melhorar a legibilidade.

Adicione espaços para diminuir a densidade do código. O espaço em branco extra dá a sensação de separação visual entre partes de uma linha.

Use um único espaço após uma vírgula entre os argumentos da função.

Não adicione um espaço após o parêntese e os argumentos da função.

Não use espaços entre o nome da função e o parêntese.

Sempre que possível, evite espaços dentro dos colchetes.

Use um único espaço antes das condições de controle de fluxo e adicione um espaço entre o operador de comparação de fluxo e os parênteses.

Use um único espaço antes e depois dos operadores de comparação.

Mantenha as linhas curtas e considere o espaço em branco horizontal. Decida uma largura padrão de linha (80–120 caracteres) e quebre uma linha longa em declarações menores em vez de deixá-la transbordar.

Como discutido anteriormente, tente manter a indentação/hierarquia. A indentação do seu código pode aumentar a legibilidade.

Não use alinhamento de coluna, a menos que seja necessário para a legibilidade. Embora esse tipo de espaçamento alinhe as variáveis, pode complicar a associação do tipo com o nome.

O alinhamento de coluna, no entanto, pode ser útil para expressões bitwise ou structs com muitos dados. Apenas esteja ciente de que isso pode criar mais trabalho para você manter o alinhamento da coluna à medida que você adiciona mais itens. Alguns formatadores automáticos também podem mudar qual parte da coluna é alinhada.

Você também pode usar o espaçamento vertical a seu favor. Mantenha partes relacionadas do script juntas e use linhas em branco a seu favor. Tente o seguinte para organizar seu código de cima para baixo:

• Agrupe métodos dependentes ou semelhantes juntos: O código precisa ser lógico e coerente. Mantenha métodos que fazem a mesma coisa próximos uns dos outros, para que alguém que lê sua lógica não precise pular pelo arquivo.
• Use o espaço em branco vertical para separar partes distintas da sua classe: Por exemplo, você pode adicionar duas linhas em branco entre:
• Declarações de variáveis e métodos
• Classes e interfaces
• blocos if-then-else (se isso ajudar na legibilidade)

Mantenha isso ao mínimo e, se possível, registre-o em seu guia de estilo.

Usando regiões em seu código

A diretiva #region permite que você colapse e oculte seções de código em arquivos C#, tornando arquivos grandes mais gerenciáveis e mais fáceis de ler.

No entanto, se você seguir o conselho geral para classes deste guia, o tamanho da sua classe deve ser gerenciável e a diretiva #region supérflua. Divida seu código em classes menores em vez de ocultar blocos de código atrás de regiões. Você ficará menos inclinado a adicionar uma região se o arquivo fonte for curto.

Observação: Muitos desenvolvedores consideram regiões como cheiros de código ou anti-padrões. Decida como uma equipe de que lado do debate você está.

Não desespere se essas regras de formatação parecerem esmagadoras. IDEs modernas tornam eficiente configurar e impor essas regras. Você pode criar um modelo de regras de formatação e, em seguida, converter seus arquivos de projeto de uma vez.

Para configurar regras de formatação para o Editor de script:

• No Visual Studio para Windows, navegue até Ferramentas > Opções, e localize Editor de Texto > C# > Formatação de Estilo de Código.
• Use as configurações para modificar as opções de Geral, Indentação, Novas Linhas, Espaçamento e Quebra.
• No Visual Studio para Mac, selecione Visual Studio > Preferências, e depois navegue até Código Fonte > Formatação de Código > Código Fonte C#.
• Selecione a Política no topo, e depois vá para a aba Estilo de Texto. Na aba Formato C#, ajuste as configurações de Indentação, Novas Linhas, Espaçamento e Quebra.

Para forçar seu arquivo de script a se conformar ao guia de estilo:

• No Visual Studio para Windows, vá para a combinação de teclas Editar > Avançado > Formatar Documento (Ctrl + K, Ctrl + D). Se você quiser formatar apenas espaços em branco e alinhamento de tabulação, você também pode usar Executar Limpeza de Código (Ctrl + K, Ctrl + E) na parte inferior do Editor.
• No Visual Studio para Mac, vá para Editar > Formatar Documento (Ctrl + I) atalho.

No Windows, você também pode compartilhar suas configurações de Editor de Ferramentas > Importar e Exportar Configurações. Exporte um arquivo com a formatação de código C# do guia de estilo e depois faça com que cada membro da equipe importe esse arquivo.

O Visual Studio ajuda você a aderir ao guia de estilo. A formatação então se torna tão simples quanto usar um atalho.

Nota: Você pode configurar um EditorConfig (veja acima) em vez de importar e exportar configurações do Visual Studio. Fazer isso facilita o compartilhamento de formatação entre diferentes IDEs. Isso também tem o benefício adicional de funcionar com controle de versão. Veja as opções de regras de estilo de código .NET para mais informações.

Embora isso não seja específico para código limpo, não deixe de conferir as 10 maneiras de acelerar seu fluxo de trabalho de programação no Unity com o Visual Studio. Lembre-se de que é mais conveniente formatar e refatorar código limpo se você aplicar essas dicas de produtividade.