Limpe seu código: Como criar seu próprio estilo de código C#

Embora exista mais de uma maneira de formatar o código do Unity C#, concordar com um estilo de código consistente para o seu projeto permite que a sua equipe desenvolva uma base de código limpa, legível e escalável. Neste blog, fornecemos algumas diretrizes e exemplos que você pode usar para desenvolver e manter seu próprio guia de estilo de código.

Observe que essas são apenas recomendações baseadas naquelas fornecidas pela Microsoft. Esta é a sua chance de se inspirar e decidir o que funciona melhor para a sua equipe.

O ideal é que um projeto Unity pareça ter sido desenvolvido por um único autor, independentemente do número de desenvolvedores que realmente trabalham nele. Um guia de estilo pode ajudar a unificar sua abordagem para criar uma base de código mais coesa.

É uma boa ideia seguir os padrões do setor sempre que possível e navegar pelos guias de estilo existentes como ponto de partida para criar o seu próprio. Em parceria com especialistas internos e externos da Unity, lançamos um novo e-book, . Crie um guia de estilo C#: Escreva um código mais limpo que se adapta ao para se inspirar, com base no estilo C# abrangente da Microsoft.

O guia de estilo do Google C# é outro recurso excelente para definir diretrizes sobre convenções de nomenclatura, formatação e comentários. Novamente, não há um método certo ou errado, mas optamos por seguir os padrões da Microsoft para nosso próprio guia.

Nosso e-book, juntamente com um arquivo C# de exemplo, está disponível gratuitamente. Ambos os recursos se concentram nas convenções de codificação mais comuns que você encontrará ao desenvolver no Unity. Essencialmente, todos esses itens são um subconjunto das diretrizes de design da estrutura da Microsoft, que incluem um grande número de práticas recomendadas além do que abordamos nesta postagem.

Recomendamos personalizar as diretrizes fornecidas em nosso guia de estilo para atender às preferências de sua equipe. Essas preferências devem ser priorizadas em relação às nossas sugestões e às diretrizes de design da estrutura da Microsoft se estiverem em conflito.

O desenvolvimento de um guia de estilo requer um investimento inicial, mas trará dividendos posteriormente. Por exemplo, o gerenciamento de um único conjunto de padrões pode reduzir o tempo que os desenvolvedores gastam para se adaptarem caso passem para outro projeto.

É claro que a consistência é fundamental. Se você seguir essas sugestões e precisar modificar seu guia de estilo no futuro, algumas operações de localização e substituição podem migrar rapidamente sua base de código.

Concentre-se em criar um guia de estilo pragmático que atenda às suas necessidades, abrangendo a maioria dos casos de uso diário. Não exagere na engenharia tentando levar em conta todos os casos extremos desde o início. O guia evoluirá organicamente ao longo do tempo, à medida que a sua equipe o utiliza em cada projeto.

A maioria dos guias de estilo inclui regras básicas de formatação. Enquanto isso, as convenções específicas de nomenclatura, a política de uso de namespaces e as estratégias para classes são áreas um tanto abstratas que podem ser refinadas com o tempo.

Vamos dar uma olhada em algumas convenções comuns de formatação e nomenclatura que você pode considerar para o seu guia de estilo.

Os dois estilos de indentação comuns no C# são o estilo Allman, que coloca as chaves de abertura em uma nova linha (também conhecido como estilo BSD do BSD Unix), e o estilo K&R, ou "one true brace style", que mantém a chave de abertura na mesma linha do cabeçalho anterior.

Em um esforço para melhorar a legibilidade, escolhemos o estilo Allman para o nosso guia, com base nas diretrizes do Microsoft Framework Design:

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

Seja qual for o estilo escolhido, certifique-se de que todos os programadores da sua equipe o sigam.

Um guia também deve indicar se os colchetes de declarações de várias linhas aninhadas devem ser incluídos. Embora a remoção das chaves no exemplo a seguir não gere um erro, a leitura pode ser confusa. É por isso que nosso guia recomenda a aplicação de aparelhos para maior clareza, mesmo que eles sejam opcionais.

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

Algo tão simples como o espaçamento horizontal pode melhorar a aparência do seu código na tela. Embora suas preferências pessoais de formatação possam variar, aqui estão algumas recomendações do nosso guia de estilo para melhorar a legibilidade geral:

• 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

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

• Use um espaço simples após a vírgula, entre os argumentos da função.

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

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

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

• Não use espaços entre o nome de uma função e os parênteses.

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

• Evite espaços dentro de colchetes.

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

• Use um espaço simples antes das condições de controle de fluxo: Adicione um espaço entre o operador de comparação de fluxo e os parênteses.

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

• Use um espaço simples antes e depois dos operadores de comparação.

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

As variáveis normalmente representam um estado, portanto, tente atribuir substantivos claros e descritivos aos seus nomes. Você pode então prefixar booleanos com um verbo para variáveis que devem indicar um valor verdadeiro ou falso. Muitas vezes, elas são a resposta a uma pergunta como, por exemplo, se o jogador está correndo? O jogo acabou? Prefixe-os com um verbo para esclarecer seu significado. Isso geralmente é associado a uma descrição ou condição, por exemplo, isPlayerDead, isWalking, hasDamageMultiplier etc.

Como os métodos executam ações, uma boa regra geral é começar seus nomes com um verbo e adicionar contexto conforme necessário, por exemplo, GetDirection, FindTarget e assim por diante, com base no tipo de retorno. Se o método tiver um tipo de retorno bool, ele também poderá ser enquadrado como uma pergunta.

Assim como as próprias variáveis booleanas, prefixe os métodos com um verbo se eles retornarem uma condição de verdadeiro-falso. Isso os expressa na forma de uma pergunta, por exemplo, IsGameOver, HasStartedTurn.

Existem várias convenções para nomear eventos e identificadores de eventos. Em nosso guia de estilo, nomeamos o evento com uma frase verbal, semelhante a um método. Escolha um nome que comunique a mudança de estado com precisão. Use o particípio presente ou passado para indicar eventos "antes" ou "depois". Por exemplo, especifique OpeningDoor para um evento antes de abrir uma porta e DoorOpened para um evento depois.

Também recomendamos que você não abrevie os nomes. Embora a economia de alguns personagens possa parecer um ganho de produtividade no curto prazo, o que é óbvio para você agora pode não ser daqui a um ano para outro colega de equipe. Os nomes das variáveis devem revelar sua intenção e ser fáceis de pronunciar. As variáveis de uma única letra são adequadas para loops e expressões matemáticas, mas, fora isso, você deve evitar abreviações. A clareza é mais importante do que o tempo economizado com a omissão de algumas vogais.

Ao mesmo tempo, use uma declaração de variável por linha; ela é menos compacta, mas também menos propensa a erros e melhora a legibilidade. Evite nomes redundantes. Se sua classe se chama Player, você não precisa criar variáveis de membro chamadas PlayerScore ou PlayerTarget. Reduza-os para Score ou Target.

Além disso, evite muitos prefixos ou codificação especial. Uma prática destacada em nosso guia é prefixar as variáveis de membros privados com um sublinhado (_) para diferenciá-las das variáveis locais. Alguns guias de estilo usam prefixos para variáveis de membros privados (m_), constantes (k_) ou variáveis estáticas (s_), de modo que o nome revela mais sobre a variável.

No entanto, é uma boa prática prefixar os nomes das interfaces com um "I" maiúsculo e segui-lo com um adjetivo que descreva a funcionalidade. Você pode até mesmo prefixar o método de captação de eventos (no assunto) com "On": O sujeito que invoca o evento geralmente o faz a partir de um método com o prefixo "On", por exemplo, OnOpeningDoor ou OnDoorOpened.

Tipo de bloco desconhecido "codeBlock", especifique um serializador para ele na propriedade `serializers.types`.

Camel case e Pascal case são padrões comuns em uso, em comparação com Snake ou Kebab case, ou notações húngaras. Nosso guia recomenda o uso de maiúsculas e minúsculas em Pascal para campos públicos, enums, classes e métodos, e de maiúsculas e minúsculas em Camel para variáveis privadas, pois essa é uma prática comum no Unity.

Há muitas regras adicionais a serem consideradas além do que foi abordado aqui. O guia de exemplo e nosso novo e-book, Crie um guia de estilo C#: Escreva um código mais limpo que seja dimensionado e forneça muitas outras dicas para uma melhor organização.

O conceito de código limpo tem como objetivo tornar o desenvolvimento mais escalonável por meio da conformidade com um conjunto de padrões de produção. Um guia de estilo deve eliminar a maior parte das suposições que os desenvolvedores teriam em relação às convenções que deveriam seguir. Em última análise, este guia deve ajudar a sua equipe a estabelecer um consenso em torno da sua base de código para transformar o seu projeto em uma produção em escala comercial.

A abrangência de seu guia de estilo depende de sua situação. Cabe à sua equipe decidir se deseja que o guia estabeleça regras para conceitos mais abstratos e intangíveis. Isso pode incluir regras para o uso de namespaces, divisão de classes ou implementação de diretivas como a diretiva #region (ou não). Embora a #region possa ajudá-lo a recolher e ocultar seções de código em arquivos C#, tornando os arquivos grandes mais gerenciáveis, ela também é um exemplo de algo que muitos desenvolvedores consideram como odores de código ou antipadrões. Portanto, convém evitar a definição de padrões rígidos para esses aspectos do estilo do código. Nem tudo precisa ser descrito no guia - às vezes é suficiente simplesmente discutir e tomar decisões em equipe.

Quando conversamos com os especialistas que ajudaram a criar nosso guia, o principal conselho deles foi a legibilidade do código acima de tudo. Aqui estão algumas dicas de como conseguir isso:

• Use menos argumentos: Os argumentos podem aumentar a complexidade de seu método. Ao reduzir seu número, você torna os métodos mais fáceis de ler e testar.
• Evite sobrecarga excessiva: Você pode gerar uma permutação infinita de sobrecargas de métodos. Selecione os poucos que refletem como você chamará o método e, em seguida, implemente-os. Se você sobrecarregar um método, evite confusão certificando-se de que cada assinatura de método tenha um número distinto de argumentos.
• Evite efeitos colaterais: Um método só precisa fazer o que seu nome anuncia. Evite modificar qualquer coisa fora de seu escopo. Passe os argumentos por valor em vez de referência quando possível. Portanto, ao enviar resultados por meio da palavra-chave out ou ref, verifique se essa é a única coisa que você pretende que o método realize. Embora os efeitos colaterais sejam úteis para determinadas tarefas, eles podem levar a consequências não intencionais. Escreva um método sem efeitos colaterais para reduzir o comportamento inesperado.

Esperamos que este blog o ajude a dar início ao desenvolvimento de seu próprio guia de estilo. Saiba mais com o nosso arquivo de exemplo em C# e com o novo e-book, no qual você pode analisar nossas regras sugeridas e personalizá-las de acordo com as preferências da sua equipe.

As especificidades das regras individuais são menos importantes do que o fato de todos concordarem em segui-las de forma consistente. Em caso de dúvida, confie no guia de evolução da sua equipe para resolver qualquer divergência de estilo. Afinal, esse é um esforço de grupo.