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.

Omitir, expandir ou modificar essas regras de exemplo para atender às necessidades da sua equipe.

Em todos os casos, considere como sua equipe implementará cada regra de formatação e, em seguida, faça com que todos a apliquem de forma uniforme. Volte ao estilo da sua equipe para resolver quaisquer discrepâncias.

Considere cada uma das seguintes sugestões de formatação de código ao configurar seu guia de estilo de desenvolvimento Unity.

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 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 de leitura e gravação, somente leitura ou somente gravação.

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

A sintaxe para propriedades pode variar, então seu guia de estilo deve definir como formatá-las. Use essas dicas para 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 o mais antigo { get; set; } sintaxe: Se você só 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 não quiser dar acesso de gravação. Alinhe o fechamento com a chave de abertura para blocos de código de várias linhas.

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]. Unity só serializa certos tipos de campo, então consulte a página de documentação para o conjunto completo de regras de serialização.

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

• Use o [SerializeField] atributo: 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 public 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 structs serializáveis para limpar o Inspector: Defina uma classe ou struct 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 "um verdadeiro estilo de chave", mantém a chave de abertura na mesma linha que o cabeçalho anterior.

Existem variações nesses estilos de indentação também. Os exemplos deste guia usam o estilo Allman das Diretrizes de Design do Microsoft Framework. Independentemente de qual você escolher como equipe, certifique-se de que todos sigam o mesmo estilo de indentação e chaves.

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 chamas entre tabs e espaços. Observe que o Visual Studio oferece a opção de converter tabs em espaços.

No Visual Studio (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.

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 mais tarde você precisar adicionar uma linha de Debug ou executar DoSomethingElse, as chaves já estarão no lugar. Manter a cláusula em uma linha separada permite que você adicione um ponto de interrupção facilmente.

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. As chaves também garantem que modificações, como adicionar nova lógica, possam ser feitas com segurança sem precisar refatorar a estrutura ao redor.

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 onde você indenta as instruções de caso. Geralmente, é recomendado incluir um caso padrão também. Mesmo que o caso padrão não seja necessário (por exemplo, em casos onde todas as possibilidades estão cobertas), incluir um garante que o código esteja preparado para lidar com valores inesperados.

Algo tão simples quanto o espaçamento pode melhorar a aparência do seu código na tela. Suas preferências pessoais de formatação podem variar, mas tente as seguintes sugestões para melhorar a legibilidade.

Adicione espaços para diminuir a densidade do código.O espaço em branco extra pode dar uma sensação de separação visual entre partes de uma linha, melhorando a legibilidade.

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. Considere o espaço em branco horizontal: Decida uma largura padrão de linha (80-120 caracteres). Quebre uma linha longa em declarações menores em vez de deixá-la transbordar.

Mantenha a indentação/hierarquia: Indente seu código para aumentar a legibilidade.

Não use alinhamento de coluna a menos que necessário para legibilidade: Esse tipo de espaçamento alinha as variáveis, mas pode dificultar 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 de 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 estas sugestões para organizar seu código de cima para baixo:

• Agrupe métodos dependentes e/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 a seu favor para separar partes distintas de 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 anote em seu guia de estilo onde for aplicável.

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.

Nota: Muitos desenvolvedores consideram regiões como cheiros de código ou antipadrõ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 scripts:

• No Visual Studio(Windows), navegue até Ferramentas > Opções. Localize Editor de Texto > C# > Estilo de Código Formatação. 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, em seguida, navegue até Código Fonte > Formatação de Código > código fonte C#. Selecione a Política no topo. Em seguida, defina seu espaçamento e indentação na aba Estilo de Texto. Na aba Formato C# , ajuste as configurações de Indentação, Novas Linhas, Espaçamento e Quebra.

Se a qualquer momento você quiser forçar seu arquivo de script a se conformar ao guia de estilo:

• No Visual Studio (Windows), vá para Editar > Avançado > Formatar Documento (Ctrl + K, Ctrl + D atalho). Se você quiser apenas formatar 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 a partir 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 facilita seguir o guia de estilo. A formatação então se torna tão simples quanto usar um atalho.

Observação: Você pode configurar um arquivo EditorConfig em vez de importar e exportar configurações do Visual Studio. Fazer isso permite que você compartilhe a formatação mais facilmente entre diferentes IDEs, e 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 10 maneiras de acelerar seu fluxo de trabalho de programação no Unity com o Visual Studio. Código limpo é muito mais fácil de formatar e refatorar se você aplicar essas dicas de produtividade.

Para configurar um arquivo .editorconfig no Visual Studio Code, siga estas etapas:

• No diretório raiz do seu projeto, crie um novo arquivo chamado .editorconfig.
• Abra o arquivo .editorconfig e adicione suas configurações de configuração desejadas.

Aqui está um exemplo de configuração para C#:

# arquivo EditorConfig mais alto

root = true

# quebras de linha estilo Unix com uma quebra de linha no final de cada arquivo

[*]

end_of_line = lf

insert_final_newline = true

# indentação de 4 espaços

[*.cs]

indent_style = space

indent_size = 4

charset = utf-8

trim_trailing_whitespace = true

# indentação de tabulação para Makefiles

[Makefile]

indent_style = tab

# configurações específicas para arquivos JSON

[*.json]

indent_style = space

indent_size = 2