REGRAS DE CODIFICAÇÃO PARA O SMARTSHARE

REGRAS DE CODIFICAÇÃO PARA O SMARTSHARE

• Métodos descrevem ações, portanto todos os métodos DEVEM conter no mínimo um verbo SEMPRE no infinitivo.

• Toda a regra de negócio DEVE ser em Português (Brasil), ou seja, a área de informática também implica num ótimo conhecimento da nossa língua.

• O nome da variável, método, classe ou propriedade e etc. DEVE possibilitar o fácil reconhecimento de sua função/funcionalidade. Não é necessário economizar espaço em disco. Os nomes de variáveis PODEM ser grandes. Se for muito exagerado, abreviar as palavras comuns como “Nome” (nm), “Data” (dt) e etc.

• O caractere underscore (_) não poderá ser usado no meio de nomes de variáveis e etc.. (Ex: string nm_pessoa; //Errado).

• Não utilizar nenhum caractere especial. Ou seja, sem acentos, sem cê-cedilha ou símbolos fora do alfabeto.

2. Usar prefixos em:

• Variáveis internas da classe • Parâmetros de métodos • Variáveis internas do método

• Ou, não usar sufixos em: namespaces, classes, propriedades ou métodos.

Tipo Prefixo Int int String str Long lng Double dbl Float flt Bool boo Object obj DateTime dt Button btn Image img CheckBox chk

DropDownList (Combo Box) ddl

Validator vld

TextBox txt

GridView grid

PlaceHolder plh

3. Comentários XML

• Todas as classes, métodos, propriedades e variáveis DEVEM conter comentários XML.

• Após o terminar de escrever a assinatura do método (tipo de retorno e parâmetros), classe ou propriedade, uma linha acima do mesmo, digitar três barras invertidas (///).

• A tag <summary> deverá conter uma BREVE descrição do que a variável, método, classe e etc... faz ou para o que serve.

• A tag <param name="parameter"> descreve cada parâmetro de um método. Se o método tiver mais de um parâmetro, haverá várias tags “param”. Descrever o que o método espera que este parâmetro seja?

• A tag <remarks> é usada para colocar um comentário adicional que não caberia no

summary. E também para chamar a atenção de quem o está usando para alguma regra interna que seja necessário saber.

• A tag <returns> serve para descrever o que resultará do método.

• Além dos comentários XML, utilizar os comentários padrão explicar lógicas em blocos de código que podem parecer confusas mesmo com a aplicação dos comentários xml e programação orientada à objetos.

• Todos os comentários servirão para gerar a documentação técnica do projeto que será disponibilizada internamente. Portanto, atentem-se as regras de português e ao profissionalismo.

4. Blocos de código e Regions:

• O código deverá ser divido basicamente em blocos e regions (Exemplo na próxima página): o Using

o Namespace o Classe o Variáveis

o Construtor (es) (ou page_load, no case de uma página asp.net) o Propriedades

Exemplo de comentários XML, estrutura do código e regions: using System; using System.Text; using System.Windows.Forms; using SmartShare.Count; using SmartShare.Database; namespace Framework_Tester.DAL { /// <summary>

/// Exemplo de uso dos comentários XML /// </summary>

class XmlComment

{

#region Variáveis internas /// <summary>

/// Indica o estado atual da página /// </summary>

private int _intVar = 10; /// <summary>

/// Indica o nome da página /// </summary>

private const String NomePagina = ""; #endregion

#region Construtores /// <summary>

/// Método construtor da classe /// </summary>

public XmlComment() {

}

/// <summary>

/// Método construtor da classe com parâmetro /// </summary>

/// <param name="parameter">

/// Objeto a ser iniciado com o construtor da classe

[a1] Comentário: A primeira parte da classe são os namespaces. Agrupar os namespaces caso venham de locais diferentes como System, Windows, SmartShare e etc...

[a2] Comentário: Localização da classe, ou tudo o que estiver dentro do mesmo

/// </param> /// <remarks>

/// A classe já inicia o objeto internamente. /// </remarks>

public XmlComment(object objParameter) {

}

#endregion

#region Propriedades públicas /// <summary>

/// Propriedade que indica o nome da pessoa /// </summary>

public String Property {

get { return ""; } }

#endregion

#region Métodos públicos /// <summary>

/// Altera a chave de criptografia /// </summary>

/// <param name="strParameter"> /// Chave nova para criptografia /// </param>

/// <returns>Nova string criptografada</returns> public String Method(String strParameter)

{ }

#endregion }

}

[a3] Comentário: O uso de regions é importantíssimo pois facilita a visualização do código criando blocos ocultáveis com comentários

5. Regras de SQL

• Os comandos, funções e palavras-chave deverão estar em letra maiúscula. Ex: SELECT, INTO, UPPER, CONVERT.

• Os nomes de tabela e seu apelido deverão estar em letra maiúscula. Ex: FROM USUARIO, DOCUMENTO DOC

• Os nomes de campos deverão estar em letra minúscula Ex: DOC.cd_documento, SELECT ds_usuario, dt_nasc

• Ao utilizar uma string de entrada do usuário como valor de comparação em um SQL (Ex: SELECT cd_documento WHERE ds_documento LIKE ‘[variavel digitada pelo usuário]’) SEMPRE “escapar” a string (em C#) para prevenir código malicioso.

• Nunca utilizar “SELECT *”. Sempre especificar cada um dos campos que serão selecionados da tabela um por um.

• Ao inserir em um campo cujo tipo seja bit (boolean) sempre trabalhar com os valores 0 ou 1 sem aspas. Nunca inserir os valores ‘true’ ou ‘false’. Lembrando que 0 significa ‘false’ e 1 significa ‘true’.

6. Banco de Dados

• Lembrar da existência do ExecuteScalar() para consultas que retornam somente uma coluna e uma linha.

• Importantíssimo lembrar que o ExecuteReader fica conectado ao banco de dados enquanto você não finalizá-lo. Execute o SQL, repasse os resultados e feche-o o mais rápido possível. • Quando for necessário executar comandos SQL recursivos, SEMPRE utilizar o objeto DataSet

(comando FillDataSet) para manipular os dados.

7. Strings

• Não será mais permitida a declaração de variáveis do tipo string primitivo (“s” com letra minúscula). Apenas a versão orientada a objeto do mesmo: String (“s” com letra maiúscula). O objeto String se encontra em System.String.

• É importantíssimo lembrar que a concatenação de strings é um processo lento. (“ola” + “ ” + “mundo” + variável...). Portanto em casos de concatenação dinâmica de strings SEMPRE utilizar a classe StringBuilder. A classe se encontra em System.Text.StringBuilder.

StringBuilder sql = new StringBuilder(); string x = ”ok”;

while( x != y) {

sql.Append(x); //Equivalente a: sql = sql + x; mas de forma muito mais rápida. }

Conn.ExecuteReader(sql.ToString()); 8. Parâmetros pela URL

• É importantíssimo utilizar nomes para a chave do parâmetro que sejam abstratos. Ou seja, se um usuário olhar a URL, não irá entender o parâmetro ou como utilizá-lo.

• Colocar nomes de chaves simples como “id”, “cd”. Com o mínimo de letras possíveis e que não formem palavras coerentes.

• Comentar internamento no código para que o desenvolvedor saiba o significado do parâmetro • Cuidar com os valores passados pela URL. Não passar informações restritas do sistema como

9. Validação de Formulário

• Todos os formulários DEVEM primariamente ser validados no servidor. A validação no cliente (javascript) deve ser usada apenas como uma facilidade extra

• Ao utilizar controles de validação do .NET, também é necessário fazer esta verificação no servidor, que é feita da seguinte forma:

Assim, todo o código dentro do bloco da validação “if(Page.IsValid)” está “protegido” no servidor.

•

automaticamente pelo .NET quando a página é carregada. Ou seja, todas as validações são executadas antes do evento Page_Load e dependendo do resultado alimenta a propriedade com True ou False. O .NET irá continuar o carregamento da página e/ou eventos que foram acionados independente do valor final da propriedade IsValid, pois cabe ao programador tomar a ação desejada baseada nesta propriedade. No caso da Tela de Gerenciamento Padrão, não há nenhum tratamento especial, simplesmente o bloco do evento fica “protegido“ da execução caso o formulário não esteja válido.

CHANGELOG:

Tópico Data Descrição

5 Adicionada regra para uso de valores bit

8 21/02/2007 Novo tópico