Padronização de Programação Para Linguagens Não Tipadas

Gostaria de começar este blog com um post do meu outro blog que eu acho um dos mais importantes documentos que já fiz na vida.

Este é um dos trabalhos que desenvolvi junto com meu amigo e ex-colega de trabalho Olavo Alexandrino que é um documento que visava padronizar o desenvolvimento de códigos-fonte da linguagem VBScript baseadas na tecnologia ASP. Porém, que posteriormente, foi modificado para que possa ser utilizado em uma gama maior de linguagens de programação não tipadas (ou fracamente tipadas) como PHP, VB Script, Java Script...

Eu tive que submeter este trabalho por quatro razões: A primeira é que este documento é baseado em pesquisas e muito tempo de estudo, além de ser baseado no conhecimento e experiências minhas e de Olavo e que estava se perdendo no esquecimento tanto por mim quanto por ele. A segunda é que eu ouvi rumores de pessoas que estão utilizando este documento como sendo de outras autorias. A terceira, é por que gostaria que outras pessoas possam utilizar este documento e altera-lo, incrementa-lo e difundi-lo pela comunidade de desenvolvimento. A quarta razão é que em grandes, médias e pequenas empresas estas tecnologias são utilizadas e não possuem um padrão de codificação (até onde eu sei) e quando possuem, normalmente, não são tão completos.

1. Comentários de Código-Fonte

Os comentários de código fonte servem não só apenas para identificar as partes do código que fazem o que na hora de fazer a manutenção dos sistemas e sim para ajudar na compreensão do código até mesmo no momento em que os sistemas que ainda estão em desenvolvimento, independente de quem está programando, pois, já é de conhecimento de todos que quando se está desenvolvendo algum sistema, é muito fácil esquecer o que aquele ou este trecho do código faz exatamente.

1. Regras de utilização de Tags de Comentários

No caso de comentários, normalmente iremos utilizar tags especificas de para facilitar a organização e por conseqüência a compreensão dos mesmos.

Seguindo algumas regras gerais dentro das linguagens:

• Todas as tags de comentário devem ser escritas em sua forma minúscula.

• Todas as tags devem conter exatamente o conteúdo referente à mesma

• Todas as tags devem estar no seu lugar especificado aqui.

2. Tags possíveis

Para facilitar a padronização do comentário de código, iremos definir algumas tags padrões para facilitar a criação dos comentários. Segue abaixo a lista dos itens que serão utilizados nos comentários dos itens.

• Description

• Access

• Author

• Date

• Version

• Package

• Param

• Return

• Var

• Example

• Tutorial

Sendo assim, temos as possíveis tags que serão utilizadas durante o processo de desenvolvimento. Sendo que cada uma tem regras e utilizações especificas dentro dos códigos.

Tag
description	descrição Tag que define a descrição do item. sintaxe @description caractere. A tag description possui estes parâmetros. Observação N/A
access	descrição Modificador de acesso do item. sintaxe @access caractere. A tag access possui estes parâmetros. Observação N/A
author	descrição Nome seguido do e-mail do autor da criação/alteração do item. sintaxe @author nome . A tag author possui estes parâmetros. Observação N/A
date	descrição Identifica a data que foi desenvolvido/alterado o item em questão. sintaxe @date data. A tag date possui estes parâmetros. Observação N/A
version	descrição Identifica a versão que foi desenvolvido/alterado o item em questão. sintaxe @date data. A tag date possui estes parâmetros. Observação N/A
copyright	descrição Nome do proprietário do código. Ex.: “MDS Tecnologia” sintaxe @copyright nome. A tag copyright possui estes parâmetros. Observação N/A
package	descrição Nome do package em que se encontra o código. Ex.: “br.com.mdstecnologia.nomesistema” sintaxe @package nome. A tag package possui estes parâmetros. Observação N/A
param	descrição Identifica o parâmetro que será enviado para um “bloco de comando” (método/função/procedimento). Sintaxe 1 @param identificador nome [direção]. Sintaxe 2 @param identificador1 nome1 [direção1] descrição1. @param identificador2 nome2 [direção2] descrição2. A tag param possui estes parâmetros. Observação O parâmetro “Identificador” deve ser o tipo da variável que será recebida, no bloco de comando. Caso exista mais de um parâmetro para o “bloco de comando” deve-se repetir a tag “param” e escrever uma linha para cada parâmetro passado.
return	descrição Identifica o parâmetro que será enviado para um “bloco de comando” (método/função/procedimento). sintaxe @return identificador. A tag return possui estes parâmetros. Observação N/A
var	descrição Descrição da variável ou propriedade. sintaxe @var identificador nome. A tag var possui estes parâmetros. Observação N/A
Example	descrição Exemplo de chamada de “blocos de comando” ou de componentes. sintaxe @example caratere. A tag example possui estes parâmetros. Observação N/A
Tutorial	Descrição Contém uma URL indicando o caminho de um arquivo que contém o “help” ou “documentação” completa do uso do item o qual o comentário se refere, contendo inclusive duvidas freqüentes, curiosidades e possíveis erros que podem ocorrer com o uso do mesmo além de melhores formas de uso entre outros. sintaxe @tutorial URL. A tag tutorial possui estes parâmetros. Observação N/A

3. Miscelânea

   1. Sintaxe de Comentários

Os blocos de comentários para documentação devem ser iniciados pelos caracteres “/**” e finalizados com “*/” e cada linha do comentário deve conter o caractere “*” no inicio de cada linha sendo os mesmos seguidos de um espaço em branco para separar as tags do mesmo. Além de que, para facilitar a leitura do comentário, devem-se alinhar os valores das tags com as declarações das tags de comentário. Conforme o exemplo a seguir.

/**

* @description Esta classe representa uma coisa

* @author Nome <e-mail@mdstecnologia.com.br>

* @date 01/01/1901

* @package br.com.mdstecnologia.projeto

* @copyright MDS Tecnologia

*/

2. Exemplos de Uso dos Comentários

Veja abaixo os exemplos de uso dos comentários

1. Comentário de arquivos

Veja abaixo os exemplos de uso dos comentários em arquivos

/**

* @description

* @author

* @date

* @package

* @copyright

*/

2. Comentário de classes

Veja abaixo os exemplos de uso dos comentários de classes

/**

* @description

* @author

* @date

* @package

* @copyright

*/

3. Comentário de métodos

Veja abaixo os exemplos de uso dos comentários de métodos

/**

* @description

* @author

* @date

* @access

* @param

* @return

*/

4. Comentário de propriedades

Veja abaixo os exemplos de uso dos comentários de propriedades

/**

* @description

* @var

*/

5. Comentário de funções

Veja abaixo os exemplos de uso dos comentários de funções

/**

* @description

* @author

* @date

* @param

* @return

* @example

* @tutorial

*/

6. Comentário de procedimentos

Veja abaixo os exemplos de uso dos comentários de procedimentos

/**

* @description

* @author

* @date

* @param

* @example

* @tutorial

*/

7. Comentário de componentes

Veja abaixo os exemplos de uso dos comentários de componentes

/**

* @description

* @version

* @author

* @date

* @package

* @param

* @return

* @example

* @tutorial

*/

8. Comentário de stored procedures

Veja abaixo os exemplos de uso dos comentários de stored procedures

/*

* @description

* @author

* @date

* @package

* @access

* @param

*/

2. Regras de Nomenclatura

Este tópico vem a ajudar na indicação e facilitar a compreensão dos códigos desenvolvidos pela MDS. Pois visa padronizar o nome das variáveis dos sistemas desenvolvidos na mesma. Tendo em vista que várias pessoas podem trabalhar no desenvolvimento de um mesmo software e provavelmente as pessoas que farão as correções e evoluções dos sistemas nem sempre serão os mesmos que desenvolveram, é de extrema necessidade para compreensão de todos o que existe nos códigos desenvolvidos pela empresa.

1. Nomenclatura de Constantes

As constantes são identificadores de memória que ao contrario das variáveis possuem valores que não podem ser alterados durante a execução dos sistemas. Ou seja, são CONSTANTES.

1. Regras de nomenclatura de Constantes

Para identificá-las utilizaremos as seguintes regras:

• O valor “CONS” no inicio dos nomes das constantes.

• As letras que compõem o nome das constantes devem ser escritas totalmente em sua forma maiúscula.

• Para separar as palavras que compõem o nome das constantes deveremos utilizar um “_” (underline).

• As palavras que compõem o nome de uma constante devem ser escritas em sua forma completa, sem uso de siglas ou abreviações.

2. Exemplos de nomenclatura de Constantes

Veja abaixo os exemplos de uso de constantes

1. Sintaxe

<CONS>_<Nome(s) que identifica(m) a constante>

2. Exemplo

CONS_CODIGO_SERVICO_ODONTOLOGIA

CONS_SEMANA

CONS_TOTAL_COLUNAS

2. Nomenclatura de Variáveis

Veja abaixo como criar as variáveis dentro dos padrões adotados.

1. Regras de nomenclatura de Variáveis

Para identificá-las utilizaremos as seguintes regras:

• Os três primeiros caracteres serão identificadores do tipo de variável.

• Os nomes das variáveis começarão com letras minúsculas (inclusive o identificador citado acima) e a partir da segunda palavra serão utilizados letras maiúsculas para a primeira letra e o restante da palavra em minúsculo. Com exceção é claro das siglas, que serão escritas todas em maiúsculas.

• Não poderá ser utilizado underline na nomenclatura das variáveis.

• As palavras que compõem o nome da variável devem ser escritas em sua forma completa e não em forma de siglas ou abreviações.

2. Identificadores do tipo de variável

Para identificar o tipo da variável, utilizaremos identificadores de tipo de variável, ou seja, um identificador de três letras para cada tipo de variável. Como se trata de um documento para varias linguagens, será utilizado tipos mais abrangentes, conforme a tabela abaixo:

Prefixo	Tipo de Variável	Descrição
str	String	Cadeia de caracteres, sem limite de comprimento.
chr	Char	Um único caractere.
int	Integer	Número inteiro.
dbl	Double Precision	Número de ponto-flutuante.
bln	Boolean	Valor lógico que pode assumir true ou false
var	Variant	Pode assumir qualquer tipo de dados
arr	Array	Um vetor/matriz. Neste caso deverá haver um outro identificador que será o tipo de valor contido no vetor/matriz
obj	Object	Um objeto instanciado qualquer. Neste caso deverá haver um outro identificador que será do tipo do objeto instanciado.

1. Regras de utilização do tipo de variável

Alguns identificadores de tipos de variáveis possuem algumas regras especiais, como citado na tabela acima. Veja abaixo algumas regras.

1. Array - Caso esteja-se declarando um array, deve-se colocar alem do identificador de array (“arr”) no inicio do nome da variável, deve-se também colocar o identificador de três letras do tipo de valor existente na mesma. Como por exemplo: temos uma variável do tipo array que possui a idade de alguns clientes. Sendo a idade dos clientes valores inteiros, colocaremos o seguinte nome no array: arrIntIdade. Tendo o identificador Int logo após o identificador arr.

2. Objeto - Seguindo a mesma linha de raciocínio deve-se aplicar a mesma regra para os objetos. Por exemplo, caso tenhamos que instanciar a classe ADODB, utilizaremos o identificador do objeto (“obj”) seguido do identificador da classe que o mesmo instanciou, este indicador pode ser uma sigla (não recomendado) ou o nome da classe que se está instanciando. Como por exemplo: objADODB. No objeto iremos encontrar uma particularidade, que seria a possibilidade de uma mesma classe ser instanciada várias vezes. Neste caso será necessário mais um identificador. Sendo este o correspondente ao valor em questão. Por exemplo: vamos supor que existe uma classe chamada “Combo” que tem por objetivo mostrar um combo em um formulário. Porém, este mesmo formulário possui um combo com valores dos nomes de pais e outro combo com valores de nomes de filhos. Neste caso teremos duas instancias da classe combo. Então utilizaremos a nomenclatura “objComboPai” para o combo do pai e “objComboFilho” para o combo que contem os nomes dos filhos.

3. Exemplos de nomenclatura de Variáveis

Veja abaixo os exemplos de uso de variáveis

1. Sintaxe

<IDENTIFICADOR(ES)><Nome(s) que identifica(m) a variável>

2. Exemplo

Veja abaixo os exemplos de variáveis com as regras gerais aplicadas

intIdadeCliente

strNomeCliente

objCliente

Veja abaixo os exemplos de variáveis com as regras específicas aplicadas

arrIntIdadeCliente

arrStrNomeCliente

objClienteLoja

objClienteFornecedor

3. Nomenclatura de Itens de Funções e Procedimentos

Veja abaixo como nomear as funções e procedimentos dentro dos padrões adotados.

1. Regras de nomenclatura de Funções e Procedimentos

Para identificá-las utilizaremos as seguintes regras:

• Os nomes das funções e procedimentos terão as palavras que a compõem letras maiúsculas na primeira letra e e a partir da segunda palavra serão utilizadas letras maiúsculas para a primeira letra e o restante da palavra em minúsculo, com exceção é claro das siglas, que serão escritas todas em maiúsculas.

2. Exemplos de nomenclatura de Funções e Procedimentos

Veja abaixo os exemplos de nomenclatura de Funções e Procedimentos

1. Sintaxe

Vide “sintaxe” de variáveis

2. Exemplo

Vide “exemplo” de variáveis

4. Nomenclatura de Itens de Conceitos de Objetos

Veja abaixo as regras dos itens que existem dentro do conceito de uso de objetos

1. Nomenclatura de Classes

As classes seguirão o modelo de Orientação a Objeto para definição de regras de nomenclatura para as mesmas.

1. Regras de nomenclatura de Classes

Para identificá-las utilizaremos as seguintes regras:

• Primeira letra de cada palavra que a identifica deve ser colocada em maiúscula, inclusive a primeira letra.

• As palavras serão escritas todas juntas, sem nenhum tipo de separador.

• As palavras que compõem o nome da classe devem ser escritas em sua forma completa e não em forma de siglas ou abreviações.

2. Exemplos de nomenclatura de Classes

Veja abaixo os exemplos de nomenclatura de Classes

1. Sintaxe

<Nome(s) que identifica(m) a classe>

2. Exemplo

Cliente

Banco

Combo

2. Nomenclatura de Atributos

Os atributos seguirão o modelo de Orientação a Objeto para definição de regras de nomenclatura para os mesmos.

1. Regras de nomenclatura de Atributos

Para identificá-los utilizaremos as seguintes regras:

• Primeira letra de cada palavra que a identifica deve ser colocada em maiúscula, inclusive a primeira letra.

• As palavras serão escritas todas juntas, sem nenhum tipo de separador.

• As palavras que compõem o nome do atributo devem ser escritas em sua forma completa e não em forma de siglas ou abreviações.

2. Exemplos de nomenclatura de Atributos

Veja abaixo os exemplos de nomenclatura de Atributos

1. Sintaxe

<Nome(s) que identifica(m) o atributo>

2. Exemplo

Cliente::Nome

Cliente::DataNascimento

Cliente::Profissao

3. Nomenclatura de Propriedades

Os atributos seguirão o modelo de Orientação a Objeto para definição de regras de nomenclatura para os mesmos.

1. Regras de nomenclatura de Propriedades

Para identificá-los utilizaremos exatamente as mesmas regras de nomenclatura de variáveis. Vide regra a cima.

2. Exemplos de nomenclatura de Propriedades

Veja abaixo os exemplos de nomenclatura de Propriedades

1. Sintaxe

Vide “sintaxe” de variáveis

2. Exemplo

Vide “exemplo” de variáveis

3. Regras de nomenclatura de Métodos

Para identificá-los utilizaremos exatamente as mesmas regras de nomenclatura de métodos. Vide regra a cima.

4. Exemplos de nomenclatura de Métodos

Veja abaixo os exemplos de nomenclatura de Métodos

1. Sintaxe

Vide “sintaxe” de variáveis

2. Exemplo

Vide “exemplo” de variáveis