REGRAS DE CODIFICAÇÃO PARA O SMARTSHARE

Transcrição

1 REGRAS DE CODIFICAÇÃO PARA O SMARTSHARE 1. Como nomear variáveis, classes métodos e etc... 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. Sintaxe:

2 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 Int String Long Double Float Bool Object DateTime Button Image CheckBox DropDownList (Combo Box) Validator TextBox GridView PlaceHolder Repeater Prefixo int str lng dbl flt boo obj dt btn img chk ddl vld txt grid plh rpt

3 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 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 o Métodos

5 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 /// Exemplo de uso dos comentários XML class XmlComment #region Variáveis internas /// Indica o estado atual da página private int _intvar = 10; /// Indica o nome da página private const String NomePagina = ""; #endregion [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 #region Construtores /// Método construtor da classe public XmlComment() /// Método construtor da classe com parâmetro /// <param name="parameter"> /// Objeto a ser iniciado com o construtor da classe

6 /// </param> /// <remarks> /// A classe já inicia o objeto internamente. /// </remarks> public XmlComment(object objparameter) #endregion #region Propriedades públicas /// Propriedade que indica o nome da pessoa public String Property get return ""; #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 #region Métodos públicos /// Altera a chave de criptografia /// <param name="strparameter"> /// Chave nova para criptografia /// </param> /// <returns>nova string criptografada</returns> public String Method(String strparameter) #endregion

7 Exemplo do mesmo código acima com as regions ocultas:

8 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.

9 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 ID dos registros sem que estejam criptografados.

10 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. Funcionamento: A propriedade da página IsValid é alimentada de True ou False 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.

11 CHANGELOG: Tópico Data Descrição 5 Adicionada regra para uso de valores bit 8 21/02/2007 Novo tópico 9 20/03/2007 Novo tópico