Esta cartilha tem como finalidade apresentar algumas boas práticas para o desenvolvimento em ambientes com SVN e outros colaboradores programadores.
Geralmente em um projeto, uma pessoa fica responsável por uma determinada área do projeto, mas pode vir a ocorrer que esta pessoa possa ter que realizar correções e/ou trabalhar em outra área do projeto.
Para que esse ciclo possa ocorrer de maneira harmoniosa, é necessário que alguns padrões sejam seguidos, tanto como nos itens de análise (espoco, casos de uso, casos de teste, etc.) como na codificação dos algoritmos da aplicação do projeto.
2 Boas práticas para codificação e entendimento
Quando um programador (pessoa) fica responsável por desenvolver uma determinada funcionalidade no projeto, o mesmo tem que respeitar alguns pontos importantes para o bom andamento de toda a equipe, dentre os pontos se destacam os seguintes.
2.1.1 Regras para nomenclaturas de Classes, Interfaces e Superclasses
Para o desenvolvimento Orientado a Objetos, toda a lógica é divida em Classes, Interfaces e Superclasses, geralmente o código desenvolvido nestes casos permite que o mesmo seja reutilizável para outros pontos da aplicação e até em outras aplicações. Para a nomenclatura destas, é recomendável que sempre se tenha um nome significativo.
Para as classes visuais, ou seja, que o seu código seja para o ‘desenho’ de uma tela de interação com o usuário, é utilizado o sufixo maiúsculo GUI ao nome da classe, como por exemplo:
- ClienteGUI;
- NotaFiscalGUI;
- AgendaGUI;
Para o caso de Interfaces visuais, se utiliza o prefixo I seguido do nome da Interface e terminando com um sufixo GUI. Exemplo:
- IFramePadraoGUI;
- IButtonPanelGUI;
- IMenuPanelGUI.
Sempre é importante seguir criando um nome significativo para a Superclasse, classe ou Interface que está sendo criada.
2.1.2 Regra para nomenclatura de atributos, métodos seletores e atribuidores
Ainda seguindo no desenvolvimento Orientado a Objetos, toda classe ou superclasse possui ou irá possuir um método seletor ou atribuidor (GET/SET) para cada um dos seus atributos, no caso de atributos, como os mesmos são de contexto geral dentro de uma classe, é necessário que o mesmo possua um nome significativo, para que não seja confundido com outro atributo ou que gere dificuldade de entendimento por outra pessoa que for realizar manutenção no código.
Exemplo:
Caso para a linguagem Java.
class Cliente {
private Object objetoPadrao;
private int quantidadePedidos;
public Object getObjectPadrao() {
return this.objetoPadrao;
}
public void setObjetoPadrao(Object o){
this.objetoPadrao = o;
}
}
Para os IDES Eclipse e NetBeans, ambos possuem um gerador de métodos seletores e atribuidores (GETTERS e SETTERS).
No caso da linguagem padrão, podem ser utilizados underlines para fazer a separação de palavras do nome de um método, variável ou atributo. Para as variáveis locais, que são utilizadas dentro de métodos e funções, deve ser mantido o padrão de nomes significativos para as mesmas.
Exemplo para o caso da linguagem Java:
Exemplo para o caso de linguagem PHP:
public Object getTotalCompras(Cliente c) {
Double total = c.getTotalCompras();
return ( (total * 25) * 10000);
}
Exemplo para o caso de linguagem PHP:
<?
public function get_total_compras(Cliente $c)
{
$total = $c->get_total_compras();
return ( ($total * 25) * 10000);
}
?>
2.1.3 Nomenclatura de variáveis para estruturas de repetição (locais)
Em casos de estruturas de repetição, são utilizadas variáveis locais para auxiliar no fluxo da lógica prevista para a situação. Nestes casos podem ser utilizadas variáveis com nomes breves. Exemplos:
Exemplo de laço foreach na linguagem PHP.
Nos casos acima, as variáveis $i e $aux, são utilizadas apenas para auxiliar na execução dos laços de repetição.
$aux = null;
foreach ($arquivos_enviados as $indice => $arquivo)
{
$aux = $arquivo.” – processado...”;
}
$aux = null;
for($i=0; $i < sizeof($arquivos_enviados); $i++)
{
$aux = $arquivos_enviados[$i++][0];
$arquivos_enviados[$i++][0]=$arquivos_enviados[$i][0];
}
Nos casos acima, as variáveis $i e $aux, são utilizadas apenas para auxiliar na execução dos laços de repetição.
2.2 Documentação e comentário para o código fonte
Um dos itens mais necessários para uma aplicação, é que o seu código possua algum tipo de documentação, tanto para explicar o funcionamento da lógica da aplicação como também da sua API.
No caso da documentação do código fonte, existem basicamente dois modelos bem comuns e práticos, o comentário de linha de execução e a documentação de referência de um método ou função.
2.2.1 Comentários de linha de execução
Em determinados pontos da aplicação, é necessário que uma lógica muito apurada e/ou complexa seja desenvolvida para solucionar o problema proposto, para estes casos é recomendado o uso de comentários sobre os passos e os ‘porquês’ de cada linha do algoritmo.
Exemplo:
// Inicia uma variável local como NULA.
$aux = null;
// Percorre todos os arquivos enviados pelo Cliente.
for($i=0; $i < sizeof($arquivos_enviados); $i++)
{
// Guarda a próxima posição do arquivo em $aux.
$aux = $arquivos_enviados[$i++][0];
// Troca a próxima posição pela posição atual.
$arquivos_enviados[$i++][0]=$arquivos_enviados[$i][0];
}
// Inicia uma variável local como NULA.
$aux = null;
// Percorre todos os arquivos enviados pelo Cliente.
for($i=0; $i < sizeof($arquivos_enviados); $i++)
{
// Guarda a próxima posição do arquivo em $aux.
$aux = $arquivos_enviados[$i++][0];
// Troca a próxima posição pela posição atual.
$arquivos_enviados[$i++][0]=$arquivos_enviados[$i][0];
}
2.2.2 Documentação da API do projeto
Um bom recurso que pode ser usado para facilitar o entendimento de futuras atualizações, estudos e desempenho da estrutura de um projeto, é aplicar ao mesmo uma documentação referente ao funcionamento da API desse projeto.
É um fato verdadeiro que grandes projetos (ou projetos de sucesso), possuíam a sua API bem documentada para que novos colaboradores/programadores pudessem estudar o seu funcionamento e poder assim corrigir problemas de segurança, adicionar novas funcionalidades além de aperfeiçoar algoritmos existentes.
Para documentar a API de um projeto de software, uma solução muito utilizada é fazer a documentação em dois pontos:
- Documentação (comentários) de linhas de execução;
- Documentação de classes, superclasses e Interfaces além dos seus respectivos métodos, funções e atributos. Este tipo de documentação geralmente pode ser compartilhado com outras pessoas (colaboradores, programadores, etc.);
Existe atualmente, uma convenção que permite que a documentação escrita nos arquivos de um projeto possa ser exportada de maneira fácil para formato PDF, HTML, XML, etc. Editores como o Eclipse IDE e NetBeans IDE, possuem plugins que agilizam a exportação da documentação escrita para o projeto.
Ao iniciar uma documentação da API de um projeto, temos que saber quais pontos necessitam de documentação, logo podemos definir os seguintes pontos:
- Superclasses;
- Classes;
- Interfaces;
- Métodos e funções;
Para o caso de projetos em PHP, é recomendado que seja adicionada na documentação dos itens 1, 2 e 3, a especificação do pacote a qual os mesmos pertencem, como por exemplo:
/**
* @package componentes/session/SessionManager.class.php
*/
Na convenção utilizada, toda a documentação deve ser iniciada pelo prefixo ‘/**’ e terminada com ‘*/’. A maioria das ferramentas que geram a documentação do projeto para outros formatos trabalham com essa notação para prefixo e sufixo.
/**
* @package componentes/session/SessionManager.class.php
*/
Na convenção utilizada, toda a documentação deve ser iniciada pelo prefixo ‘/**’ e terminada com ‘*/’. A maioria das ferramentas que geram a documentação do projeto para outros formatos trabalham com essa notação para prefixo e sufixo.
2.2.3 Parâmetros para a documentação de uma API
O modelo de documentação de API possui algumas chaves que padronizadas, ou seja, elas fazem parte de uma especificação aberta para que qualquer pessoa que leia possa entender (ponto de vista técnico) e todas as ferramentas de exportação de documentação interpretam corretamente estas chaves.
Para o caso de desenvolvimento de software, as documentações geradas geralmente são no idioma inglês, geralmente visto em casos de softwares de código livre que são abertos aos usuários para o seu estudo. Mas para casos empresariais, pode ser gerada uma documentação de referência e estudo apenas para o pessoal da equipe envolvida no desenvolvimento ou para futuros estudos por parte de novos colaboradores (desenvolvedores).
Uma relação das chaves padronizadas para documentações de API pode ser visualizada na tabela abaixo.
TAG
DESCRIÇÃO
@author
Para armazenar o nome do programador que criou a classe, superclasse ou Interface.
@date
Data em que foi criado o arquivo.
@package
Caminho absoluto do arquivo dentro do projeto ou apenas o nome do pacote/pasta onde o mesmo se encontra.
@version
Número da versão estável, geralmente associada ao número gerado pelo servidor SVN do projeto.
@copyright
Informações de direitos autorais do autor.
@license
Informações sobre o tipo da licença. Geralmente utilizado para frameworks e bibliotecas de terceiros.
@params
Informações sobre um determinado parâmetro da função ou método. Deve-se especificar o nome do parâmetro, tipo, e uma descrição do motivo.
@returns
Informações sobre o retorno do método ou função, definindo o tipo do retorno e as informações que são retornadas com a variável de retorno.
@since
Utilizado para definir se uma função, método ou atributo está presente a partir somente de um determinado número de versão.
@see
Atalho ou nome de referência para uma leitura ou consulta de outro recurso ou componente do projeto.
@decrapted
O atributo, método ou função que não seja mais utilizado, mas esteja ainda ‘em modo legado’ recebe esse atributo na sua documentação como forma de aviso para que não seja mais utilizado para futuras atualizações.
@exception
Relação das exceções capturas do método ou função atual.
Nada impede que sejam criadas chaves especificas para representar alguma informação julgada como importante, como por exemplo:
@last_commit 12/12/2008 14:55 Juca Aparecido
Um exemplo de uma classe documentada pode ser visualizado logo abaixo:
<?
/**
* Classe responsável por gerenciar toda a lógica de acesso a
* dados para os Clientes da aplicação.
*
* @author Carlos Alberto Junior
* @package modelo/dao/
*
* @version 1.1.4
* @see componentes/conexao/Connection.class.php
*/
class ClienteDAO extends Connection
{
/**
* Ponteiro de result set para esta classe.
*/
private $result_set = null;
/**
* Retorna uma lista de clientes aplicando um filtro para
* não trazer os clientes que foram marcados como
* excluídos.
*
* @params string $ordem nome do campo para realizar a
* ordenação da consulta dos clientes.
* @returns array $this->result_set uma coleção de objetos
* do tipo ‘Cliente’.
*/
public function busca_clientes($ordem = ‘c.nome_completo’)
{
$sql = “select
c.nome_completo,
c.idade,
c.email
from
cliente c
where
c.excluido = ‘N’
order by
”.$ordem;
try
{
$this->result_set = mysql_query($sql);
}
catch(Exception $e)
{
echo “Problema na execução da SQL”;
return null;
}
return $this->result_set;
}
}
?>
3 Referências
Colocar tudo por escrito, disponível em: http://producingoss.com/pt-pt/written-rules.html
Documentando seus códigos Java, disponível em: http://webinsider.uol.com.br/index.php/2000/09/14/documentando-seus-codigos-java/
How to write Doc comments for the Javadoc Tool, disponível em: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
Version Control, disponível em: http://producingoss.com/pt-pt/vc.html#vc-singularity
TAG
DESCRIÇÃO
@author
Para armazenar o nome do programador que criou a classe, superclasse ou Interface.
@date
Data em que foi criado o arquivo.
@package
Caminho absoluto do arquivo dentro do projeto ou apenas o nome do pacote/pasta onde o mesmo se encontra.
@version
Número da versão estável, geralmente associada ao número gerado pelo servidor SVN do projeto.
@copyright
Informações de direitos autorais do autor.
@license
Informações sobre o tipo da licença. Geralmente utilizado para frameworks e bibliotecas de terceiros.
@params
Informações sobre um determinado parâmetro da função ou método. Deve-se especificar o nome do parâmetro, tipo, e uma descrição do motivo.
@returns
Informações sobre o retorno do método ou função, definindo o tipo do retorno e as informações que são retornadas com a variável de retorno.
@since
Utilizado para definir se uma função, método ou atributo está presente a partir somente de um determinado número de versão.
@see
Atalho ou nome de referência para uma leitura ou consulta de outro recurso ou componente do projeto.
@decrapted
O atributo, método ou função que não seja mais utilizado, mas esteja ainda ‘em modo legado’ recebe esse atributo na sua documentação como forma de aviso para que não seja mais utilizado para futuras atualizações.
@exception
Relação das exceções capturas do método ou função atual.
Nada impede que sejam criadas chaves especificas para representar alguma informação julgada como importante, como por exemplo:
@last_commit 12/12/2008 14:55 Juca Aparecido
Um exemplo de uma classe documentada pode ser visualizado logo abaixo:
<?
/**
* Classe responsável por gerenciar toda a lógica de acesso a
* dados para os Clientes da aplicação.
*
* @author Carlos Alberto Junior
* @package modelo/dao/
*
* @version 1.1.4
* @see componentes/conexao/Connection.class.php
*/
class ClienteDAO extends Connection
{
/**
* Ponteiro de result set para esta classe.
*/
private $result_set = null;
/**
* Retorna uma lista de clientes aplicando um filtro para
* não trazer os clientes que foram marcados como
* excluídos.
*
* @params string $ordem nome do campo para realizar a
* ordenação da consulta dos clientes.
* @returns array $this->result_set uma coleção de objetos
* do tipo ‘Cliente’.
*/
public function busca_clientes($ordem = ‘c.nome_completo’)
{
$sql = “select
c.nome_completo,
c.idade,
c.email
from
cliente c
where
c.excluido = ‘N’
order by
”.$ordem;
try
{
$this->result_set = mysql_query($sql);
}
catch(Exception $e)
{
echo “Problema na execução da SQL”;
return null;
}
return $this->result_set;
}
}
?>
3 Referências
Colocar tudo por escrito, disponível em: http://producingoss.com/pt-pt/written-rules.html
Documentando seus códigos Java, disponível em: http://webinsider.uol.com.br/index.php/2000/09/14/documentando-seus-codigos-java/
How to write Doc comments for the Javadoc Tool, disponível em: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
Version Control, disponível em: http://producingoss.com/pt-pt/vc.html#vc-singularity
Set as favorite
Bookmark
Email This
Hits: 655
