Padrão de Codificação

ASP.NET

Saturday, January 1, 2011

Padrão de Codificação para .NET
C#.NET

     Olá pessoal, meu nome é Mauricio Júnior e estou disposto a colocar para vocês um documento de padrão para codificação de sistemas e códigos. Dessa forma, se todos programarem de uma mesma forma dentro de uma empresa ou sistema, o código será entendido por qualquer pessoa no futuro que for executar alguma modificação no sistema. Esse tipo de documento é ótimo para começar um sistema por uma equipe, tudo se torna mais fácil e ágil programar.

Índice Analítico
1.   Introdução   4
2.   Padrões de desenvolvimento C#   4
2.1   Endentação de código   4
2.2   Comentários   4
2.2.1   Comentários de classes e métodos   5
2.3   Declarações   6
2.3.1   Variáveis privadas de classe   6
2.3.2   Variáveis locais   6
2.3.3   Namespace   6
2.3.4   Interface   6
2.3.5   Métodos   6
2.3.6   Enumerações   6
2.3.7   Eventos   7
2.3.8   Constantes   7
2.3.9   Exceções   7
2.3.10   Propriedades públicas   7
2.3.11   Windows Forms   7
2.3.12   Objeto de dados   10
2.3.13   Variáveis   10
2.3.14   Web Forms   11
2.4   Considerações   11
3.   Referências   12

1.   Introdução
Este documento tem como objetivo elaborar uma padronização para o desenvolvimento em C#, considerando os seguintes tópicos:

•   Padronização de nomenclatura usada na programação de métodos, objetos, variáveis e constantes. Além disso, trata como deverá ser feita a documentação dentro do código.


2.   Padrões de desenvolvimento C#
2.1   Endentação de código
Alguns trechos de código podem ficar muito extensos e você deverá encarar o dilema de quebrar a linha.
• Quebrar a linha após uma vírgula;
• Quebrar a linha após um operador;
• Alinhar a nova linha no inicio da expressão no mesmo nível da linha anterior.
Exemplo:
longMethodCall(expr1, expr2, expr3,
                      expr4, expr5);
e
var = a * b / (c - g + f) +
         4 * z;
Outro fator importante é a utilização de espaços em branco para endentação. Não use espaços em branco para endentação, use tabulação. Motivos: Facilidade de incrementar e decrementar blocos de código através de atalhos de teclas do editor de código.
2.2   Comentários
Utilizar as três barras “///” para comentários de classes e métodos. O motivo é utilizar a funcionalidade do Visual Studio .NET de transformar comentários em documentação de código. Entretanto, para comentários que não necessitam ser publicados, seguem algumas sugestões:
O comentário é importante para você ou outra pessoa ser orientada sobre a manutenção de um código fonte, tenha atenção à forma de destacar o comentário. Por exemplo, comentários com mais de uma linha poderiam ser assim:
/** Line 1
* Line 2
* Line 3
**/
Para comentários de uma linha somente, o comentário deve ser uma espécie de marcador de loops ou não deve ser aplicado. A questão é que como exposto em linhas anteriores, os comentários devem chamar a atenção visando facilitar e direcionar a manutenção. Somente justifica-se um comentário de uma linha quando você necessita marcar dentro de um bloco de código o início de um nível de endentação ou loop. Exemplo:
//Verifica se somente uma string foi entrada
if(args.Length==1)
      Console.WriteLine(args[0]);
else
{
      ArgumentOutOfRangeException ex;
      ex = new ArgumentOutOfRangeException("Utilize somente uma string");
      throw(ex);
}
Outra boa aplicação para comentários de uma linha é a explicação de uma declaração. Por exemplo:
int levelStatus; // nível do status
int sizeStatus; // tamanho do status

2.2.1   Comentários de classes e métodos
Toda classe e método devem ser documentados. O padrão utilizado segue abaixo:
/// <summary>
/// Retorna DirectoryEntry representando a unidade organizacional.
/// </summary>
/// <param name="coopCentral">Cooperativa Central.</param>
/// <param name="cooperativa">Cooperativa desejada</param>
/// <returns>
/// Resulado da busca no AD.
/// </returns>
/// <exception cref="ActiveDirectoryManager.ActiveDirectoryManagerException">
/// Se não for encontrada a unidade organizacional.
/// </exception>
/// <remarks>
/// Criado por: <nome>
/// Alterado por: <nome>
/// </remarks>

2.3   Declarações
2.3.1   Variáveis privadas de classe
Utilizar a definição CamelCase (a primeira letra do identificador é minúscula e a primeira letra de cada identificador subseqüente concatenado é maiúscula).
Exemplo:
String firstName;
2.3.2   Variáveis locais
Utilizar a definição CamelCase.

2.3.3   Namespace
Utiliza-se o nome da empresa seguido pelo nome do projeto, camada de negocio e o modulo que está sendo desenvolvido.
Exemplo:
Bancoob.NomeProjeto.CamadaNegocio.AccessControl
2.3.4   Interface
O nome de interface deve ser PascalCase (a primeira letra do identificador é maiúscula e a primeira letra de cada identificador subseqüente concatenado é maiúscula), e começar com o prefixo “I”, para indicar que o tipo é uma interface.
Exemplo:
IServiceProvider

2.3.5   Métodos
Utilizar a definição PascalCase.
2.3.6   Enumerações
Utilizar a definição PascalCase.
2.3.7   Eventos
Utilizar a definição PascalCase para o nome do evento.
Utilizar o sufixo EventHandler para o nome do delegate associado ao evento. Especificar dois parâmetros “sender” e “e”. O parâmetro “sender” representa o objeto que disparou o evento e deve ser sempre do tipo Object, mesmo sendo possível utilizar um tipo especifico. O estado associado com o evento é encapsulado em uma instancia de um evento de classe chamado “e”.
Exemplos:
public delegate void MouseEventHandler (object sender, MouseEventArgs e)
public event MouseEventHandler Click;

2.3.8   Constantes
Nomes de constantes deverão ser todos maiúsculos com as palavras separadas por um underscore.
Exemplo:
A2A_MAX
2.3.9   Exceções
O nome de uma classe de exceção deve utilizar a definição PascalCase, e finalizar com a expressão Exception, para indicar que o tipo é uma exceção.
Exemplo:
ServiceProviderException

2.3.10   Propriedades públicas
Utilizar a definição PascalCase para o nome de propriedades.
Exemplo:
public int PrinterStatus
     {
     }

2.3.11   Windows Forms
Abaixo temos a lista de componentes e os prefixos:
Componente    Prefixo    Exemplo
Assembly   asm
Button    btn    btnExit
Char   ch    chxxx
CheckBox    chk    chkReadOnly
CheckedListBox    clb    clbOptions
ColorDialog    cld    cldText
ComboBox    cbo    cboEnglish
Container   ctr
ContextMenu    cmn    cmnOpen
CrystalReportViewer    rpt    rptSales
DataColumn   dcol
DataGrid    grd    grdQueryResult
DataGridDateTimePickerColumn   dgdtpc
DataGridTableStyle   dgts
DataGridTextBoxColumn   dgtbc
DataReader   dreader
DataRow   drow
DataTable   dtable
Dialog   dialog
DialogResult   dr
DomainUpDown    upd    updPages
ErrorProvider    err    errOpen
Exception   ex
FontDialog    ftd    ftdText
Form    frm    frmEntry
GroupBox    grp    grpActions
HashTable   htbl
HelpProvider    hlp    hlpOptions
HScrollBar    hsb    hsbMove
ImageList    ils    ilsAllIcons
Label    lbl    lblHelpMessage
LinkLabel    lnk    lnkEmail
ListBox    lst    lstPolicyCodes
ListView    lvw    lvwHeadings
MarshallByRefObject   rmt
Mainmenu   mm
MDI-Frame   frame
MDI-Sheet   sheet
Menu    mnu    mnuFileOpen
MenuItem   mi
MonthCalendar    mcl    mclPeriod
NotifyIcon    nti    ntiOpen
NumericUpDown    nud    nudPieces
OpenFileDialog    ofd    ofdImage
PageSetup Dialog    psd    psdReport
Panel    pnl    pnlGroup
PictureBox    pic    picIcon
PrintDialog    ptd    ptdText
PrintDocument    prn    prnText
PrintPreviewControl    ppc    ppcText
PrintPreviewDialog    ppd    ppdText
ProgressBar    prg    prgLoadFile
RadioButton    rad    radType
RichTextBox    rtf    rtfReport
SaveFileDialog    sfd    sfdImage
SDI-Form   form
Splitter    Spt    sptDivision
StatusBar    sta    staDateTime
TabControl    tbc    tbcOptions
TextBox    txt    txtLastName
Timer    tmr    tmrAlarm
ToolBar    tlb    tlbActions
ToolTip    tip    tipIcons
TrackBar    trb    trbIndex
TreeView    tre    treOrganization
UserControl   usr
VScrollBar    vsb    vsbMove
WindowsPrincipal   wpl

2.3.12   Objeto de dados
Abaixo temos alguns componentes de comunicação de dados:
Componente    Prefixo    Exemplo
DataSet    dts    dtsProducts
DataView    dtv    dtvConsult
OleDbCommand    ocm    ocmConsult
OleDbConnection    ocn    ocnClients
OleDbDataAdapter    oda    odaClients
SqlCommand    scm    scmConsult
SqlConnection    scn    scnClients
SqlDataAdapter    sda    sdaClients

2.3.13   Variáveis
Veja a lista abaixo de tipos e prefixos:
Tipo    Prefixo
String, string   str
Boolean   bln
Byte   byt
Int16, int32   int
Long   lng
Single   sgn
Double   dbl
Currency   cur
Date Time   dtm
Variant   var
Array   ary
User-defined type   typ
Enum   enu
Collection Object   col

2.3.14   Web Forms
Veja a lista abaixo de tipos e prefixos:
Tipo    Prefixo
AdRotator   adrtr
Button   btn
Calendar   cldr
CheckBox   cbx
CheckBoxList   cbxl
CompareValidator   cvdr
CrystalReportViewer   crvwr
DataGrid   dgrd
DataList   dlst
DropDownList   ddl
HyperLink   hlnk
Image   img
ImageButton   ibtn
Label   lbl
LinkButton   lbtn
ListBox   lbx
Literal   ltrl
Panel   pnl
PlaceHolder   phdr
RadioButton   rbtn
RadioButtonList   rbtnl
RangeValidator   rvdr
RegularExpressionValidator   rev
Repeater   rptr
RequiredFieldValidator   rfv
Table   tbl
TextBox   tbx
ValidationSummary   vsmy
Xml   xml

2.4   Considerações
Ao declarar variáveis, procure seguir as considerações abaixo.
Ao invés de:
int a, b;
usar:
int a; // Valor de entrada 1
int b; // Valor de entrada 2

Sempre inicializar suas variáveis no local aonde são declaradas.
int a = 1; Valor de entrada 1

3.   Referências
1.   http://www.microsoft.com/brasil/msdn/Tecnologias/visualc/visual_c_boaspraticas.aspx
2.   http://www.akadia.com/services/naming_conventions.html