Regras de Codificação Semi-Resumido

Arquitetura de Sistemas Padrão de Nomenclatura e Codificação .NET / C#

1. NOMENCLATURA C#

1.1.Variáveis Locais

Formato (regra da nomenclatura)

<Identificador>[<Complemento>]

Onde:

<Identificador>: utiliza à regra Camel Case, ou seja, todos os caracteres deste identificador devem estar em minúsculo.

<Complemento>: utilizar o primeiro caractere em maiúsculo.

Exemplos de uso (correto)

public override int ProcessLine(){

string codigoUsuario = null; int codigoErro = 0;

Exemplos de uso (incorreto)

public override int ProcessLine(){

string strCodUsuario = null; int CodigoErro = 0;

1.2.Variáveis de Classe


_<Identificador>[<Complemento>]

Onde:



separadores de termos. (A diferenciação pode ser obtida pelo fato de cada termo utilizar o primeiro caractere em maiúsculo).

21/4/2023 Página 1 de 35



public class Produto{ #region Atributos privados private int _colunaInicial; private int _tamanhoLinha; private string _identificadorCampo; private string _nome; #endregion


public class Produto{ #region Atributos privados private int colunaInicial = 0; private int TamanhoLinha = 0; private string _nomeProduto = ""; #endregion

1.3.Parâmetros de Métodos



Onde:



separadores de termos. (A diferenciação pode ser obtida pelo fato de cada termo utilizar o primeiro caractere em maiúsculo).


public int GetFieldRules(string codigoCampo) {


public int GetFieldRules(string codigoCampo_) {

21/4/2023 Página 2 de 35


1.4.Constantes


<Identificador>[_<Complemento>]

Onde:

<Identificador>: Todas as letras devem estar em maiúsculas.

Caso seja necessário adicionar um complemento ao nome da constante, com o objetivo de clarificar sua função, recomendamos o uso do “_” como caractere separador.

<Complemento>: O primeiro caractere formador do complemento devem estar em maiúsculo.


public class Produto{ #region Constantes private const string CODIGO_LINGUA = “BRA”; private const string CODIGO_MOEDA = “BRL”; #endregion


public class Produto{ #region Constantes private const string CODIGOLINGUA = “BRA”; private const string codigoMoeda = “BRL”; #endregion

21/4/2023 Página 3 de 35


1.5.Classes



Onde:

<Identificador>: utiliza à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.

<Complemento>: utiliza o primeiro caractere em maiúsculo.

Outras informações

Além do formato descrito acima, vale reforçar:

Na formação do nome da classe, evitar o uso de prefixos tais como cCliente, CCliente etc; prefira Cliente.

No caso da classe for um controller devemos sempre deixar o após o nome o sufixo Controller.

Especificamente para o caso onde o identificador começa com a letra I, pode haver alguma confusão com a nomenclatura adotada para a Interface. Porém deve-se ressaltar que na nomenclatura de interfaces, a primeira letra é I maiúscula seguida de uma segunda letra também em maiúscula; diferentemente da declaração de classes, onde temos apenas o primeiro caractere do identificador em maiúsculo.


public class Produto{ #region Constantes private const string CODIGO_LINGUA = “BRA”; private const string CODIGO_MOEDA = “BRL”; #endregion...public class ListaPreco{ #region Constantes private const string CODIGO_MERCADORIA = “001”; private const string CODIGO_MOEDA = “BRL”;

21/4/2023 Página 4 de 35


#endregion

public class PrecoController{


public class produto{ #region Constantes private const string CODIGOLINGUA = “BRA”; private const string codigoMoeda = “BRL”; #endregion

...public class item_venda{ #region Constantes private const string CODIGOMERCADORIA = “001”;

...public class listaPreco{ #region Constantes private const string CODIGOMOEDA = “BRL”;

1.6.Propriedades



Onde:

<Identificador> : Os identificadores utilizam à regra Pascal Case, ou seja, o primeiro caractere deve ser grafado em maiúscula seguido de caracteres em minúsculo.

<Complemento> : utiliza o primeiro caractere em maiúsculo.


21/4/2023 Página 5 de 35


public string NomeProduto { get; set; }


private string _nomeProduto;

...public string nome_Produto{ get { return _nomeProduto; } set { _nomeProduto = value; }}

...public string produtos_estocados{ get { return _nomeProduto; } set { _nomeProduto = value; }}

1.7.Exceção


Excecao<Identificador>[<Complemento>]

Onde:

Excecao: Constante que indica o tipo da classe.

21/4/2023 Página 6 de 35


<Identificador> : utiliza à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.



class ExcecaoArquivoNaoEncontrado : Exception{

public ExcecaoArquivoNaoEncontrado (string str){

Console.WriteLine(“Arquivo não encontrado”);}

}


class ArquivoNaoEncontrado : Exception{public ArquivoNaoEncontrado(string str){

Console.WriteLine(“Arquivo não encontrado”);}}...class _arquivoNaoEncontrado: Exception{public _arquivoNaoEncontrado (string str){

Console.WriteLine(“Arquivo não encontrado”);}}

1.8.Métodos



Onde:

21/4/2023 Página 7 de 35


<Identificador> : Os identificadores utilizam à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.



public class Cliente{private bool Incluir(string cpf){

...


public class Cliente{private bool validar_Cliente(string cpf){

......

public class Cliente{private bool validacaoCliente(string cpf_){

...

1.9. Interfaces


<I><Identificador>[<Complemento>]

Onde:

<I> : Caractere “I” em maiúsculo como prefixo para definir que se trata de uma interface




Não utilize “_” ou outro caractere de separação para declaração de um nome de interface.

21/4/2023 Página 8 de 35



interface INode{ string Texto { get; set; }}


interface Interface_Node{ string Texto { get; set; }}

...interface MeuNode{ string Texto { get; set; }}

1.10. Enumeradores



Onde:


21/4/2023 Página 9 de 35




Assim como o nome do Enum type, os nomes referentes ao Enum values type devem seguir a mesma regra de nomenclatura.

Não utilize abreveações para definir um Enum, nem utilize o sufixo “Enum” para nomear um enumeration.

Outro ponto importante: Evite prefixar os elementos do enum com o identificador do enum. Por exemplo, se o tipo do Enum for DigitalResolution, evitar nomear os membros como DigitalResolution800, DigitalResolution1000, etc.


enum DiasSemana {Domingo = 0, Segunda, Terca, Quarta, Quinta, Sexta, Sabado};


enum dias_semana {Domingo = 0, Segunda, Terca, Quarta, Quinta, Sexta, Sabado};enum _diasSemana {Domingo = 0, Segunda, Terca, Quarta, Quinta, Sexta, Sabado};enum EnumDias {_domingo = 0, _segunda, _terca, _quarta, _quinta, _sexta, _sabado};enum TipoImagem {TipoImagemBitmap = 0, TipoImagemGIF, TipoImagemTIFF };

1.11. Namespaces


<CompanyName><Type><ApplicationName>[<Package>[<Feature>]]

Onde:

<CompanyName> : O CompanyName utiliza à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.

<Type> : Tipo do namespace (Arquitetura ou Aplicação).

<ApplicationName> : Identificação do nome da aplicação (ou class library). ApplicationName deve utilizar à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.

<Package> : Identifica um grupo de funcionalidades. Package utiliza à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.

21/4/2023 Página 10 de 35


<Feature> : Identifica uma funcionalidade de aplicação (ou class library). Feature utiliza à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.


Para uso no exemplo abaixo temos:

CompanyName = Belagricola

Type = Arquitetura

ApplicationName = Cockpit

Package = Comunicacao (Conjunto de classes que implementam a Comunicação)


namespace Belagricola.Arquitetura.Cockpit.Comunicacao


namespace Belagricola.ARQUITETURA.cokpit.Comunicacaonamespace teste.comunicacao

1.12. Controles de Formulários


<prefixo de tipo de elemento><Identificador>[<Complemento>]

Onde:

<Prefixo de tipo de elemento> : Prefixo único de 3 caracteres usados como identificador do tipo de controle.

<Identificador> utiliza

à regra Pascal Case, ou seja, a primeira letra do identificador deve estar em maiúscula seguida das demais letras em minúscula.

Prefixo Elementolbl Labelhpl HyperLink

21/4/2023 Página 11 de 35


txt Texto Boxopt Radio Buttonchk Check Boxpnl Panelimg Imagedg DataGridbtn Buttonddl DropDown List boxcbo Combo Boxmsk Masked Text Boxgrp Group Boxuc User Controltela ITelacontrole IControle


imgIDTMUN, txtCodigoSistema, lblIDTMun

(*) Os nomes dos controles devem ser gerados usando a notação húngara com os prefixos conforme definidos na tabela acima.


IDTMUN, IdtMun

21/4/2023 Página 12 de 35


2. REGRAS DE CODIFICAÇÃO

2.1.Utilização de constantes

Descrição

Não utilize números e strings hard-coded, prefira o uso de constantes.

Motivo

Como os valores desejados estão definidos em uma constante, torna-se mais fácil a manutenção do código caso seja necessário alterar tais valores.


switch(tipoEmail) { case EMAIL_HTML: ... break; case EMAIL_TEXTO: ... break;

}

...if (produto.Moeda == CODIGO_REAL){ ...}


switch(tipoEmail) { case “Html”: ... break; case “Texto”: ... break;

}

21/4/2023 Página 13 de 35


...if (produto.Moeda == 21){ ...}

2.2.Regiões de código

Descrição

Utilize sempre o bloco region para organizar o código de uma classe.

Utilizar as seguintes regiões

- “Constantes” para organizar as constantes;

- “Atributos” para organizar os atributos;

- “Construtores” para organizar os construtores;

- “Métodos Privados” para organizar os métodos privados;

- “Métodos Públicos” para organizar os métodos públicos;

- “Métodos Privados Estáticos” para organizar os métodos privados e estáticos;

- “Métodos Públicos Estáticos” para organizar os métodos públicos e estáticos;


Caso o programador deseje utilizar um comentário em uma determinada etapa de seu código ele poderá realizar utilizando “//” acima do comando desejado.

Todos os comentários devem ser feitos em Português.


#region Atributos

private string _nome = string.Empty;

#endregion

#region Constantes

private const string CODIGO_LINGUA = "BRA";

#endregion

#region Construtores

21/4/2023 Página 14 de 35


public Fornecedor(){}

#endregion

#region Métodos Privados

private bool Incluir(string cpf){

return true;}

#endregion

#region Métodos Públicos

public bool Persistir(string cpf){

return true;}

#endregion

#region Métodos Privados Estáticos

private static bool Inserir(){

return true;}

#endregion

#region Métodos Públicos Estáticos

public static bool Persistir(string cpf){

return true;}

#endregion

21/4/2023 Página 15 de 35


2.3.Comentários

Descrição

Utilize sempre o bloco summary antes de uma classe ou um método publico. O bloco summary deve descrever o objetivo da classe ou método e, utilizando a tag param quando necessário, os parâmetros de entrada que possui.

Todavia, caso o programador não deseje adicionar um resumo a uma rotina específica ele pode utilizar a forma “/* ... */“ para realizar o comentário desejado.

Motivo

Utilizando a tag de summary, o Visual Studio .NET interpreta internamente tal comentário como descrição da classe/método.


Caso o programador deseje utilizar um comentário em uma determinada etapa de seu código ele poderá realizar utilizando “//” acima do comando desejado.

Todos os comentários devem ser feitos em Português.


/// <summary>/// Descrição Descrição Descrição Descrição Descrição Descrição/// </summary>/// <param name="parametro1">Descricao</param>/// <param name="parametro2">Descricao</param>/// <returns>Descricao</returns>private bool MyClass(string parametro1, string parametro2){ ...

...// Valida a existência de um registro no array if (myArray.Length > 0) { ...


21/4/2023 Página 16 de 35


// Descrição Descrição Descrição Descrição Descriçãoprivate bool MyClass(string parametro1, string parametro2){ ...

.../// <summary>/// Valida a existência de um registro no array/// </summary>/// <returns></returns> if (myArray.Length > 0) { ...

2.4.Comentários II

Descrição

Não escreva comentários para cada linha de código ou para cada declaração de variável.

Motivo

Escreva comentários apenas onde é necessário, de tal forma que o código não fique poluído e de difícil leitura.

21/4/2023 Página 17 de 35


2.5.Tabulação e espaçamento

Descrição

Utilize sempre <TAB> (de 4 espaços) para alinhamento, nunca utilize <ESPAÇO> para definir coluneamento.

Motivo

Utilizando <TAB> o programador mantém um padrão para o coluneamento, tornando o código mais legível e agradável, principalmente a quem prestará manutenção.


private void MyClass(){ if (...) { for (...) { //codigo ... } }}



21/4/2023 Página 18 de 35


2.6.Marcadores de inicio de bloco

Descrição

Evite colocar o marcador de início de bloco na mesma linha do comando (if, for, while, etc.). Nestas construções, coloque o marcador em linha separada.

Motivo

O uso do marcador de início de bloco em linhas separadas aumenta consideravelmente a legibilidade do programa.





21/4/2023 Página 19 de 35


2.7.Marcadores de inicio de bloco II

Descrição

Os blocos subseqüentes ao comando if sempre devem sempre possuir os marcadores de bloco.

Motivo

Evitar erros de codificação por erros de compreensão durante a digitação/leitura do código.




private void MyClass(){ if (...) for (...) { //codigo ... } }

21/4/2023 Página 20 de 35


2.8.Tamanho de arquivos

Descrição

Evite a construção de arquivos fontes muito grandes. Se um arquivo de programa fonte estiver com mais de 400 linhas, provavelmente ela não está bem estruturada.

Motivo

Arquivos muito grandes indicam que a classe nela contida tem muita lógica implementada e provavelmente não está desenhada de forma a hierarquizar e estruturar os componentes de forma organizada. Nestas situações há fortes indícios de que a modelagem de objetos aplicada está degenerada ou compondo mais de uma entidade numa só.

2.9.Tamanho de métodos

Descrição

Evite a construção de métodos com mais de 30 linhas de código.

Motivo

Métodos com muitas linhas de código têm sua legibilidade comprometida e provavelmente o índice de reutilização de código está comprometido.

21/4/2023 Página 21 de 35


2.10. Construções não autorizadas

Descrição

É proibido utilizar nomes que coincidam com as palavras reservadas do .NET Framework.

Também é vetada a utilização de atributos públicos dentro das classes, deve-se utilizar propriedades.

Motivo

Criar variáveis com nomes semelhantes às palavras reservadas do .NET pode confundir a interpretação de campos. Esta prática dificulta a identificação de se a variável trata-se ou não de uma definição de campo ou simplesmente uma variável.

Já o uso dos atributos públicos não é recomendável devido ao comportamento destes que isola o campo dentro da classe onde declarado, e possui o conceito de hereditariedade.


public string NomeProduto{ get; set; }


private string[] collections;

21/4/2023 Página 22 de 35


2.11. Comando Switch

Descrição

Ao utilizar a construção switch/case, deve-se sempre definir o tratamento padrão (entrada default).

Motivo

A definição do tratamento padrão obriga o desenvolvedor a pensar na situação de exceção já durante a codificação, ao invés de adicionar o tratamento quando alguma condição de exceção e inesperada ocorra e faça com que nenhuma das opções listadas no switch/case seja executada.


switch(condição){ case AAA: {

...break

} case AAB:

{...break

} default: {

...break

}}


switch(condição){ case AAA: {

...break

} case AAB:

21/4/2023 Página 23 de 35


{...break

}}

2.12. Tratamento de exceção

Descrição

Ao utilizar a construção try/catch, nunca construa a lógica do catch com implementação vazia.

Motivo

Este tipo de construção realiza o tratamento da ocorrência do erro que pode ser propagado para as demais camadas da aplicação, tornando o programa instável de difícil depuração.


try{

… executar logica}catch (System.Exception e){

// gravar o erro// executar o tratamento para esta condição

}


try{

… executar logica}catch (System.Exception e){

// ignorar a ocorrência do erroReturn;

}

21/4/2023 Página 24 de 35


2.13. Validação Local I

Descrição

As validações funcionais de negócio das informações inseridas pelo usuário durante a execução de um programa deverão ser realizadas nas classes de negócio. Nenhuma validação de regra de negócio deve existir na apresentação.

Motivo

Para maximizar a reutilização das regras de negócio codificadas para uma aplicação, é importante que toda a regra de negócio seja codificada em uma mesma camada da arquitetura da solução. Além disso, esta camada deve estar localizada na arquitetura de forma que sua reutilização seja realmente proveitosa. Neste sentido, se codificarmos regras de negócio na camada de apresentação, estaremos eliminando a possibilidade de reutilização desta regra em outras aplicações. Desta forma, as validações funcionais deverão ser realizadas nas classes do projeto de negócio.


if (classeNegocio.ValidaPermicao(usuario)){

Executar Mensagem de Erro}


if (usuario.Permicao == 11){

Executar Regra de Negócio}

21/4/2023 Página 25 de 35


2.14. Validação Local II

Descrição

Existem algumas validações estruturais das informações inseridas pelo usuário que devem fazer parte da validação na apresentação, por exemplo, validações de Formato de Data, CPF, CNPJ, e-mail, Código Conta Corrente, entre outros.

Motivo

Estas validações devem ocorrer na apresentação para possibilitar uma maior performance do sistema. Todas as informações que possam ser inseridas por usuários em diferentes partes do sistema e tenham sua estrutura previamente especificada, poderão fazer parte desta validação. As funções de validações deverão estar especificadas em uma mesma biblioteca facilitando sua utilização.


if (!(VerificarEmail(usuario.Email)){

Executar Mensagem de Erro}

21/4/2023 Página 26 de 35


3. BOAS PRÁTICAS

3.1.Uso de sufixos proibidos

Descrição

Existem alguns sufixos que devem ter sua utilização evitada por serem usados para outro propósito. Desta forma, deve-se evitar o uso dos seguintes sufixos:

- Attribute

- Collection

- Dictionary

- EventArgs

- EventHandler

- Exception

- Queue

- Stack

- Stream

- Delegate

- Enum

- Flags

- Impl.

Motivo

Os sufixos listados acima já são usados por tipos básicos do framework .net e desta forma o seu uso pode causar confusão aos desenvolvedores.

21/4/2023 Página 27 de 35


3.2.Variáveis

Descrição

Sempre evite a declaração de mais de uma variável do mesmo tipo em uma só linha. Sempre que possível, tabular um bloco lógico.

Sempre que possível prefira o tipo implícito “var” como ele deixamos o código mais limpo.

Motivo

Isso facilita a visualização das variáveis e seus respectivos tipos bem como seus valores iniciais. Também evita que ocorra uma condição imprevista por falta de um conteúdo válido atribuído à variável.

Exemplos de uso

string nome;string sexo;int idade;string usuario;var sobreNome;

3.3.Espaçamento

Descrição

Sempre utilize um espaço simples para a separação de operadores e vírgulas/ponto e vírgula em uma mesma instrução.

Motivo

Utilizando esta prática, a interpretação da instrução fica mais simples e legível.

Exemplos de uso

for(var i = 0; i < total; i++){

BuscaNome(param1, param2);

...int total = valor1 + valor2;

21/4/2023 Página 28 de 35


21/4/2023 Página 29 de 35


3.4.Abreviações

Descrição

Evite o uso de abreviações na formação de nomes, salvo quando sejam abreviações bastante conhecidas. Por exemplo: UI para User-Interface.

Motivo

Evitando a utilização de abreviações, o nome formado tem seu verdadeiro significado, evitando causar dúvidas durante a interpretação de sua funcionalidade.

Exemplos de uso

private bool ObtemCredito(){

...

...string NomeCliente = “Joao”;private const string TIPO_CREDITO = “001”;

3.5.Uso de caixa alta/baixa

Descrição

Evite o uso de nomes que requerem diferenciação entre maiúsculas e minúsculas, ou seja, não criar elementos cujos nomes, se convertidos todos os caracteres para maiúsculas tornam-se iguais. O mesmo vale para a criação de namespaces.

Motivo

Algumas linguagens não fazem diferenciação entre letras maiúsculas e minúsculas e isto pode dificultar a reutilização de componentes entre estes ambientes.

Exemplo

void Analyser()

21/4/2023 Página 30 de 35


{...

...}

void analyser(){

......}

21/4/2023 Página 31 de 35


3.6.Construção de mais de um comando na mesma linha

Descrição

Evite a codificação de mais de um comando na mesma linha.

Motivo

Este tipo de construção dificulta a legibilidade do programa, sem trazer qualquer outro benefício.

Exemplo (Correto)

userAge++; userName += CONST_VALUE;

Exemplo (Incorreto)

userAge++; userName = += CONST_VALUE “”;

21/4/2023 Página 32 de 35


3.7.Especialização de métodos

Descrição

Ao definir a funcionalidade de um método, cuidar para que o mesmo realize apenas uma tarefa. Evite a construção de métodos que fazem mais de uma atividade.

Motivo

Ao construir métodos que realizam uma única tarefa, mesmo que ela seja muito simples, estamos implicitamente promovendo a reusabilidade do mesmo.

Exemplo (Correto)

public int SendMail(string address, string msg);

public int SendSMS(string address, string msg);

Exemplo (Incorreto)

public int SendMailSMS(string address, string msg, int tipo);

21/4/2023 Página 33 de 35


3.8.Evitar a declaração de parâmetros não usados em métodos

Descrição

Ao definir a assinatura de um método, assegurar que todos os parâmetros definidos em sua lista sejam referenciados pela lógica interna do método.

Motivo

Parâmetros não utilizados internamente implicam em consumo desnecessário de memória e CPU, consequentemente degradando a performance do programa.

21/4/2023 Página 34 de 35


4. GLOSSÁRIO

A seguir temos a descrição de alguns dos termos utilizados neste documento.

Pascal Case: Termo normalmente usado para definir uma prática de nomear identificadores. A regra consiste em escrever palavras compostas ou frases onde as palavras são concatenadas sem espaço e cada palavra tem a primeira letra em maiúscula e as demais em minúscula.

Camel Case: Termo normalmente usado para definir uma prática de nomear identificadores. A regra consiste em escrever palavras compostas ou frases onde as palavras são concatenadas sem espaço e cada palavra (com a exceção da primeira) tem a primeira letra em maiúscula e as demais em minúscula. A primeira palavra deve ter todas as letras em minúsculas.

Notação Húngara: Termo normalmente usado para definir a convenção usada para nomear objetos utilizando seu tipo como prefixo do nome. Nesta notação, os nomes de variáveis começam com uma ou mais letras cujo mnemônico representa o tipo da variável seguido de outra palavra usada para identificar a função da mesma.

21/4/2023 Página 35 de 35

Documents

Regras de Codificação Semi-Resumido