52

Reconheço que é comum que cada linguagem utilize um padrão para compor seus identificadores (variáveis, constantes, objetos, controles etc).

No caso do C#, quais seriam as boas práticas com relação à maiúsculas/minúsculas, tamanho e utilização de caracteres especiais?

0

3 Respostas 3

52
  • Adote o mesmo padrão de maiúsculas do .NET segundo a tabela abaixo. Quando usar acrônimos, prefira manter só a primeira letra em maiúscula para facilitar a leitura. O membro ser estático, constante ou somente leitura não afeta o padrão. Há controvérsias se campos protegidos realmente devem ser camelCase ou é melhor com PascalCase. Depende se você está considerando ele mais próximo de ser privado ou mais próximo de ser público.
PascalCase camelCase
Classes Variáveis locais
Assembly Parâmetros de métodos
Classes Campos privados e protegidos
Structs
Intefaces (sempre com o I antes do nomes)
Delegates
Enums
Métodos
Propriedades
Campos públicos
Eventos

Recomendações gerais de escrita

  • Tente usar uma forma mais fluente para dar entendimento ao que se pretende mas não exagere. Procure usar uma linguagem que seja adequada ao domínio que está sendo desenvolvido para aquela tarefa específica.
  • Raramente um número deve fazer parte de um nome de qualquer identificador. Se usar ele deve ter algum significado. Ex.: Norma452.
  • Evite nomes que podem ser confundidos com alguma outra coisa. Ex.: b001.
  • Procure manter nomes semelhantes para coisas semelhantes.
  • Nomes devem ser fáceis de serem localizados com ferramentas de busca em código. Você deve achar facilmente o que está querendo, preferencialmente nada mais e nada menos do que o desejado. Tenha isto em mente.
  • Decida se vai usar acentuação em identificadores ou não e mantenha o padrão, se aceitar acentos, todo mundo tem que respeitar a acentuação correta, não pode ficar escolhendo momentos para não acentuar.
  • DoThis() pode ser ótimo como exemplo generalizado mas não tem nenhum significado para o código. O mais importante é dar nomes significativos. Principalmente não dê nomes que signifiquem outra coisa, mesmo que eventualmente. Ex.: string nonBlank = " ";
  • Procure entender as sutilezas dos nomes. Counter é um contador, Count é uma contagem e TotalCount é o totalizador da contagem. Seja o mais específico possível. SalveNome() é melhor que SalveCampo() a não ser que o segundo salve qualquer campo a ser especificado.
  • Evite abreviações a não ser que faça sentido para todos e não crie ambiguidades. A abreviação pode ser tão conhecida que ela pode ser até melhor. Ex.: Ftp, UI, IO, DB, PK, AlgumaCoisaInfo, Config, ValorIcms, Id, Args, ex (para o que só pode ser exceção), i para loops (i tem um significado óbvio para qualquer programador), temp ou mesmo tmp (mas não use ambas). Em variáveis locais a abreviação não é tão problemática se não criar mnemônicos incompreensíveis. O melhor é evitá-las, mas não precisa exagerar. Passa ser problema se tudo estiver abreviado ou não dê para entender a intenção da variável por qualquer programador com o mínimo de experiência. Não me pergunte porque é melhor PascalCase em Ftp mas ALLCAPS em UI, IO, etc. Eu imagino que seja o fato de ter apenas duas letras no acrônimo. Já Id é uma só palavra. Há quem prefira ID. Eu não, mas mantenho um padrão.
  • Não use underscore (sublinhado) em nomes de identificadores a não ser que tenha um motivo muito forte, talvez para evitar conflitos possíveis em código lidando com situações em mais baixo nível (geradores). Especialmente não use o prefixo m_. O sublinhado pode ser usado para um parâmetro irrelevante em uma lambda. Ex.: (_, __) => FazAlgo(); quando você sabe que precisa receber dois argumentos mas eles não serão usados na sua execução.
  • Já ficou claro que notação húngara não deve ser usada. Um identificador deve indicar o significado dele naquele contexto e não alguma característica técnica dele. No entanto você dizer que está usando um TextBox com descrição não é notação húngara, é importante para entender o que é aquele identificador. Já um método GetInt() pode ser já que não está dizendo o que está pegando e sim o tipo do que está pegando, a intenção é esta, não é uma simples característica. carArray provavelmente é húngara, prefira carros.
  • Evite palavras reservadas usualmente presentes em outras linguagens que funcionam em cima da CLR.
  • Se o tipo fizer sentido em um nome de identificador (tipicamente um método), prefira o nome do tipo conhecido pela CLR e não o nome definido no C#, assim o identificador pode ser facilmente usado em outros linguagens. Até poderia evitar isto em identificadores privados ou que é absolutamente certo que nunca será usado em outra linguagem, mas por coerência, é melhor não criar exceções. Isto vale para nomear identificadores, não para usar declaração de tipo.
  • Procure alguns termos comuns fáceis e padronize seu uso quando realmente não dá para identificar o significado do identificador ou ele não é relevante. Use value ou valor, item, etc.
  • Tente achar a semântica correta do que está tentando fazer e principalmente manter uma relação correta entre termos que se complementam. Por exemplo: Begin vem antes de um End, não confundir como um Start que vem antes de um Stop e um Initiate antes de Finish, um Open antes de Close, Lock antes de Unlock, Block e Deblock, Head e Tail, Header e Footer, Before e After, Read e Write, Input e Output, First e Last, Previous e Next, Increment e Decrement, Enter e Leave, Add e Remove, Create e Destroy, Insert e Delete, Show e Hide, Suspend e Resume, Top e Bottom, etc. Outros são mais complicados de afirmar ou depende de contexto. Do casa com Cancel? E Go tem relação com Quit? Ou o inverso entre os termos anteriores? E que tal o uso Run, Execute, Perform, Abort?. É bom aprender antes de usar. Entenda a diferença entre Find, Seek, Search, Lookup, Scan, Traverse, Locate, Select, Query, Pick, Trace, GetAbcXxx e assemelhados e suas traduções. Não se atenha a estas palavras, são apenas exemplos de conceitos parecidos que podem ser definidos mais precisamente com a palavra correta. Calcule é diferente de Pegue que é diferente de Leia. Uma propriedade TemPedidos é muito diferente de um método VerifiqueExistênciaDePedidos(). Entenda a diferença entre Increment, Add, Plus e Accumulate. Escolha nomes que identifiquem se haverá efeito colateral, mutação do objeto ou não.
  • Evite nomes que cause duplo negativo quando usa um operador de not. Ex.: !family.hasNoChildren. Seja afirmativo.
  • Se está difícil dar um nome à um tipo ou método provavelmente ele faz mais do que deveria ou não está claro o que ele faz ou porque existe. Se precisa usar um And ou E tem chance de algo estar errado.
  • Não costuma haver problemas em usar uma variável ou propriedade com o mesmo nome do tipo como camelCase (Color color = Color.Red;). Isto só deve ser evitado se o nome da variável não indica bem o que ela está fazendo ali. O significado contextual pode ser perdido quando se adota este padrão (talvez melhor Color statusColor = Color.Red;).
  • Identificadores de tipos booleanos podem, ou mesmo devem, ter prefixos indicando uma capacidade. Ex.: is, can, has, isThere (alguns preferem usar só o has), allow (que pode ser o mesmo que can). Ou em português é ou eh, está ou estah (costuma ser seguido de um verbo no particípio ou adjetivo), pode (normalmente seguido de um verbo no infinitivo), tem (provavelmente seguido de um substantivo), Existe (seguido de substantivo). O plural pode ser usado, ou outra conjugação, ex.: foiTentado. E lembre-se que uma enumeração costuma dar mais semântica que um booleano, mesmo quando só existe dois estados. A semântica do booleano é apenas dizer se é verdadeiro ou falso, não use para outras coisas que possuem apenas dois estados.

Variáveis

  • Variáveis que guardam coleções podem estar no plural. Isto é válido na maioria dos casos mas há situações que pode não ser o ideal. Há quem use coletivo nestes casos.
  • Em eventos é comum usar o sufixo EventArgs para o parâmetro que vai receber os argumentos do evento. Isto deixa claro a intenção deste parâmetro. Provavelmente este parâmetro será um tipo subclasse do tipo EventArgs.
  • Variáveis podem ter várias formas conforme o contexto mas o mais comum é que sejam substantivos.

Tipos

  • Classes, estruturas e enumerações devem ser substantivos mesmo que adjetivados ou compostos. Interfaces podem ser substantivos ou adjetivos indicando uma capacidade, sendo comum terminar em able ou ável. Em alguns projetos classes abstratas costumam levar o sufixo Base. Tenho minhas dúvidas se isto é consistente, até onde sei não é recomendado pela Microsoft. Usar o nome da classe base como parte do nome da nova classe derivada costuma ser uma boa opção mas é preciso cuidado para não haver exageros e ter nomes longos demais que acabam não identificando bem o que é a classe.
  • Classes estáticas com métodos de extensão devem ter o sufixo Extension. Há quem ache que Ext é suficiente. Em alguns casos uma classe estática normal pode ter o sufixo Utility ou Helper mas estas classes devem ser evitadas. Se ela tiver alguma função bem definida o sufixo é desnecessário. Se espelhe na Math e Console.
  • Enumerações devem usar o singular a não ser nos raros casos que faça muito mais sentido estar no plural que é o caso do uso como [Flags]. E não use um prefixo ou sufixo Enum no nome. Redundâncias deste tipo em outras coisas, principalmente em nomes de colunas em banco de dados é um dos maiores abusos que vejo em nomenclatura.
  • Exceções devem ter o sufixo Exception para evitar confusões. Desta forma deixa claro para o que deve ser usado.
  • Atributos devem terminar com Attribute na sua definição. O próprio compilador sabe que o uso dos atributos não usam o sufixo, ou seja, ele sabe inequivocamente que aquilo é um atributo e que o nome original precisa de um sufixo. Não colocar o sufixo na declaração pode trazer problemas, assim como colocar no uso.
  • Há quem diga que tipos delegados devem ter o sufixo Delegate. Há quem ache desnecessário. A Microsoft costuma usar o sufixo mas parece ser "tão necessário" quanto o sufixo Enum em uma enumeração. Prefira usar uma lambda e não se preocupe com isto :).
  • Prefira usar letras únicas maiúsculas para identificar os slots de tipos genéricos (T, U, K, V). Se tiver um bom motivo pode usar palavras mais significativas mas não use nomes que podem ser confundidos com tipos existentes (você nunca sabe quando vai gerar confusão), especialmente não use Type para evitar confusão com o tipo Type. Se for usar um nome mais descritivo utilize o prefixo T. Ex.: TKey e TValue.

Membros de tipos

  • Métodos costumam ser verbos, principalmente no imperativo, muitas vezes seguidos do substantivo a que se referem. Um método é uma ação que você está mandando o computador fazer. Delegados não costumam diferir de métodos comuns. Mas estas regras podem variar para dar uma leitura mais fluente para o que se deseja. Só não tente fazer que todo o código se pareça com o inglês fluente, ou pior, com o português, porque isto não é possível sem tornar o código ainda mais confuso. O método pode indicar em seu nome o que eles estão retornando (mas em geral, não seu tipo), especialmente os que começam com Get ou Pegue ou Compute, etc. Há quem use PegarXXX() ou CalcularXXX que aparentemente seria o infinitivo. Não sei se isto é um erro por desconhecimento ou há algum motivo para a escolha consciente. Acredito mais no primeiro.
  • O sufixo Async deve sempre ser usado em métodos que possuem esta característica. É importante identificar um método com uma característica tão especial e ajuda distinguir da versão síncrona.
  • Eventos são verbos no gerúndio (pré-evento) ou particípio passado (pós-evento) conforme a situação. Evite criar eventos com sufixo Before ou After ou nomes parecidos. Se o evento deve executar a ação o nome deve ser no infinitivo. Ex.: Deleting, Deleted e Delete. Os manipuladores de eventos devem ter o prefixo on. Há controvérsias se deveria existir a forma aportuguesada para on.
  • Propriedades e campos públicos tendem a ser usados como adjetivos. Se usar como verbo, pode ter algo errado.
  • Membros de enumerações podem assumir várias formas, substantivos, adjetivos, verbos em alguma conjugação.
  • Evite colocar os chamados "membros sentinela" que são membros artificiais de enumerações que ajudam manipulá-las. Coloque apenas membros naturais ao domínio. Ex.: NotSelected.
  • Evite qualquer redundância a não ser que ela sirva para evitar ambiguidade. Prefira Line.GetLength() à Line.GetLineLength().

Arquivo, Assembly e Namespace

  • Use uma classe por arquivo e nomeie o arquivo com o mesmo nome da classe.
  • Prefira usar nomes totalmente qualificados (incluindo o namespace) em exemplos pequenos ou arquivos curtos onde apenas um membro de um namespace é usado. E prefira usar a diretiva using sempre que for usar vários membros de um namespace em arquivos maiores (maioria dos casos).
  • Não nomeie namespaces com um domínio de internet (talvez o pior caso de super-engenharia que já vi). Você pode usar o nome da empresa e depois o nome do produto ou tecnologia em um subgrupo mas não tente tornar o nome único abusando dos subgrupos. Se realmente o nome da empresa responsável pelo namespace for muito comum, utilize uma variação que deixe único. O ponto deve ser usado para separar agrupamentos que façam sentido e não para separar palavras. Prefira ServiceModel à Service.Model.
  • Namespaces não devem ter o mesmo nome de tipos membros dele. Se isto for necessário, tente fazer alguma alteração como colocar o namespace no plural. Lembre-se que é possível ter alguma redundância em namespaces já que eles não aparecem obrigatoriamente no uso de seus membros. Então ter uma classe XmlDocument dentro do NS Xml não é um exagero redundante.
  • Evite criar membros poluindo namespaces que você não criou (de terceiros). O melhor motivo para não seguir esta recomendação é a criação de métodos de extensão, mas não abuse disto.
  • Sempre que possível o nome de um assembly deve seguir o nome do namespace. Organizar um namespace (pelo menos a parte principal dele) por assembly é uma boa organização mas não precisa ser seguida cegamente.

Miscelânea

  • Em uma API mais moderna use o mesmo nome da antiga com um sufixo indicando que é a versão nova, se possível indicando a novidade. Isto facilita achar ambas. Ou prefira um nome nome que seja mais significativo quando o nome anterior não havia sido bem escolhido. Ex.: AlgumaCoisaAsync, FazAlgoEx.
  • Quando realmente não for possível dar um bom nome para um identificador use um comentário próximo da declaração para ajudar dar melhor entendimento. Mas isto deve ser raro.
  • Não relacionado com o nome mas com a legibilidade: declare as variáveis o mais perto possível de onde ela vai ser usada, não existe mais necessidade ou vantagem em declarar tudo no começo do código. Os membros sim, podem ser declarados organizados pela sua função no tipo.
  • Se o desenvolvimento for internacional tudo deve estar em inglês. Se for certo que nunca sairá do domínio do seu país, pode usar a sua língua onde o domínio está na sua língua. Deixe em inglês as coisas mais técnicas, o domínio mais ligado ao mecanismo.
  • Quando diretrizes conflitam você tem que escolher uma, óbvio. Eu prefiro escolher a que me parece causar menos problemas ou pelo menos que me agrada mais. Isto costuma bater com o que a linguagem/framework prefere. Ex.: CA1500 vem do compilador. SA1309 vem de uma ferramenta externa. Eu prefiro a primeira. Porque me parece mais limpo e não causa nenhum problema.
  • Evite trazer para o C# convenções excelentes (ou nem tanto) de outras linguagens. Eu já identifico que um programador é preguiçoso ou não sabe programar em C# quando ele coloca constantes como ALL CAPS. Isto era útil em C porque era a única forma de indicar, pelo menos para o programador, que um identificador era uma constante. Depois isso deixou de ser importante mas as pessoas continuaram fazê-lo (leia sobre a experiência com macacos, aqui no SOpt acontece muito isto, só não pode achar que fazer o que sempre foi feito está errado por definição, o problema é não saber porque). Levaram isto para outras novas linguagens por influência de seus autores ou por vontade própria. Este exemplo é uma variação de notação húngara. Você usa uma convenção para demonstrar algo que não precisa ser demonstrado e pior, que pode ser alterado no futuro, mesmo que não devesse.

A maioria destas recomendações foram definidas pelos criadores da linguagem/framework para facilitar e padronizar o entendimento do código por todos. O mais importante é manter uma consistência entre uma equipe. Porém se você pensar que seu código pode acabar sendo compartilhado com pessoas que você ainda não conhece (aqui por exemplo) é melhor tentar seguir padrões universais.

É claro que algumas convenções ajudam mais que outras e o que mais ajuda é manter clareza do que está tentando indicar ali. Isto só costuma ser fácil fazer quando você domina totalmente o problema. Nomear alguma coisa eventualmente já é difícil, imagina nomear milhares de coisas que você não domina em alguns dias de trabalho.

Estas convenções facilitam a leitura e manutenção do projeto. Indiretamente pensar sobre isto ajuda entender o que você está fazendo. Mas procure entender as motivações para a recomendação, isto pode lhe ajudar mais, pode ajudar seu código ser melhor escrito além da nomenclatura.

Obviamente não fiz uma lista completa de convenções e muito menos expliquei cada uma.

A resposta do AP já deu boas indicações do que se deve fazer para tentar atingir um resultado melhor, tentei me ater a alguns guidelines que encontrei e que sigo ou que você poderia seguir.

Discordo um pouco de tomar cuidado com nomes que podem impactar tráfego de dados. Isto não deveria ser uma preocupação. Se for importante (normalmente não é) é melhor criar uma maneira pós-código de reduzir do tamanho. A questão do underline não é a recomendação oficial mas claro que em convenções não existe o certo e errado, só estou ressaltando isto. Linguagem ubíqua pode ser uma boa se não entenderem errado o que é isto, que não exagere. Normalmente é difícil achar consenso universal do que é mais ubíquo. Sinceramente não sei se é melhor nomeTextBox ou textBoxNome (isto é um TextBox do Nome ou é um Nome encapsulado em um TextBox?), então escolho um e mantenho a consistência.

Como já foi dito você pode usar ferramentas para ajudar a forçar estes padrões, mas só uma pequena parte é possível. Pode dar uma olhada nas regras já existentes no StyleCop e poderá criar suas próprias.

Lembre-se sempre que se houver um bom motivo, não siga a recomendação. Saiba que algumas deslizadas serão punidas de forma mais intensa que outras. E o principal, nenhuma convenção é obrigatória. Não gosta? Acha que é problemático? Existe um bom motivo para não seguir em determinado momento? Use outra forma. Convenções e guias são como boas práticas, só são bons quando você sabe quando não seguir.

StyleCop evolui.

Guia de estilo do próprio .NET.

No SO tem muitas respostas sobre o assunto de forma individualizada.

Escrevo mais sobre o assunto nessa resposta.

Posso ter errado em alguma coisa, comente.

Coloquei no GitHub para referência futura.

4
  • "Tente usar uma forma mais fluente para dar entendimento ao que se pretende mas não exagere. Procure usar uma linguagem que seja adequada ao domínio que está sendo desenvolvido para aquela tarefa específica." - Acho isso primordial, acredito que é o que mais pode facilitar o entendimento do código. Commented 17/09/2014 às 12:43
  • Sabe me dizer se é preferível utilizar _ (underline) no início de um campo privado? Fico muito confuso, vejo códigos com ele, outros não. O VS também me confunde, quando ele cria os campos privados e atribui o valor a partir dos parâmetros do construtor, ele não utiliza o _, porém quando é pra converter em uma propriedade completa, acho que é assim que está lá, ele utiliza =/ Commented 16/08/2018 às 22:01
  • 1
    @ViníciusLima você pode usar, mas não é o padrão adota, não há vantagem nisto se adotar os outros padrões. Quem o faz não segue o padrão, inclusive o Visual Studio. Tem coisas ruins nele e na documentação.
    – Maniero
    Commented 16/08/2018 às 22:16
  • 1
    Resposta excelente!! Deveria estar como a aceita.
    – SUR1C4T3
    Commented 3/09/2018 às 13:13
25

De um modo geral, para o C#, o padrão camel case é amplamente utilizado. Resumindo, nesse padrão, os nomes são compostos simplesmente unindo-os sem qualquer tipo de separador, como o sublinhado (_). O que ajuda a diferenciar as palavras é o FatoDeCadaUmaIniciarComMaiúscula. Além disso, escolher bem o nome do elemento pode contribuir - e muito - para o entendimento de seu código pela equipe (e por você mesmo, na hora de voltar depois de uns meses para uma eventual manutenção). Abaixo algumas considerações que podem facilitar na hora de escolher o nome de seus identificadores:

Seja claro!

Em primeiro lugar, escolha um nome que dê sentido àquele elemento. Leia novamente o código, como se fosse um texto em português e tente avaliar se a frase que acabou de ler faz sentido, ou seja, se é coerente e não induz o leitor à qualquer tipo de ambiguidade. Se você não lembra pra que serve uma variável (x é um péssimo nome), é provável que tenha escolhido o nome errado.

Abreviações

Geralmente, siglas e abreviações tendem a atrapalhar o entendimento do código, a menos que sejam amplamente utilizadas por todos na equipe e na empresa. Um padrão cada vez mais em desuso, a notação húngara, prevê o uso de abreviações para a nomeação de controles e até hoje muita gente a usa para dar nomes a elementos do banco de dados. Assim, uma caixa de texto poderia se chamar txtNome. Ao optar por uma linguagem mais eloquente, a abreviação seria substituída por textBoxNome.

Linguagem ubíqua

Por influência de Eric Evans, em seu livro Domain Driven Design, há uma tendência em atribuir nomes que expressem antes o negócio e depois a tecnologia. Pra um desenvolvedor isso representa um desafio, pois nos expressamos a maior parte do tempo usando uma linguagem essencialmente técnica e cheia de termos próprios. Focando no negócio, o controle txtNome passaria a ser chamado nomeTextBox, por exempo. Linguagem ubíqua é considerada aquela que todos os envolvidos falam, que está presente no vocabulário cotidiano da organização e facilita o entendimento de um conceito por todos.

Maiúsculas e minúsculas

No padrão CamelCase é comum que haja distinção para a primeira inicial:

  • para Classes, é em maiúscula: SituacaoVenda. Para Constantes e Enumeradores também.
  • para objetos, controles e variáveis, em minúscula: notaFiscal, contadorItemNotaFiscal.

Tamanho

O limite para o tamanho do nome de um identificador é o bom senso apenas, não há limitação imposta pelo framework. Assim, nomes muito extensos podem ocupar muito espaço na tela e atrapalhar a leitura. É bom lembrar também que, para nomes de controles na web (na view, propriamente), a questão do tamanho pode impactar o tráfego de dados, já que cada caractere representa um byte.

Caracteres especias

No C#, é comum usar o sublinhado (underline, underscore) para inicializar os campos privados, também conhecidos como atributos. São aqueles elementos declarados no escopo da classe e, portanto, disponíveis para todos os métodos dessa classe. Assim, um campo para representar o repositório de clientes poderia se chamar _clienteRepositorio.

Toda linguagem possui suas palavras reservadas (key words). No C# é possível usar o arroba (@) se for muito necessário que uma variável se chame class, por exemplo (@class).

Ferramentas de produtividade

O próprio Visual Studio sugere nomes para controles usando esses padrões. Se você cria um item de menu com a descrição Clientes, a IDE vai sugerir que o respectivo nome do controle seja clientesMenuItem, por exemplo.

Outra ferramenta que implementa essas práticas é o ReSharper, da JetBrains. Essa ferramenta já sugere um conjunto bem mais abrangente de boas práticas, destacando no código a nomenclatura que foge ao padrão.

2
  • Resposta bem completa. Parabéns. Commented 5/09/2014 às 19:30
  • @GuilhermeJSantos e a minha resposta é completa? :)
    – Maniero
    Commented 18/09/2015 às 11:45
4

Existe um padrão de nomeação das variáveis e facilita na codificação

Métodos => Letra Maiúscula na primeira letra exemplo: private void GetCadastrarUsuario()

Propreties => Letra Maiúscula na primeira letra exemplo: public String Nome { set; get; }

Event => Letra Maiúscula na primeira letra exemplo: public event EventHandler OnChange;

Variáveis Globais no escopo da Class => Utilizar o '_' antes do nome da variável exemplo: int _variavelExemplo = 0;

Variáveis Internas: => exemplo: int valor = 0;

Obs: Quando se referência a algum item do layout através do C# é importante colocar o exemplo : this.ButtonSave , pois facilita identificar de onde vem essa variável.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .