Formatação e Escrita de Código

De BIS Wiki
Ir para navegação Ir para pesquisar

O BIS utiliza alguns padrões de escrita do código para facilitar o desenvolvimento em equipe. Algumas são recomendadas pelo própria comunidade Java, outras foram criadas para o projeto. Algumas das vantagens desse método são:

  • fácil manutenção de código fonte escrita por outro desenvolvedor ou pelo mesmo, já que com o passar do tempo todo desenvolvedor acaba alterando seu estilo de código.
  • evita erros de interpretação com os nomes dos métodos, chamando um método que se "achava" que faria uma coisa devido ao seu nome enquanto acaba fazendo outra.
  • facilita a verificação dos métodos já existentes. Em um sistema muito extenso e feito ao longo de anos e por mais de um desenvolvedor, é comum que não se conheça ou não se lembre dos métodos e funções já existentes. Nomes fora de padrão permitiriam que métodos possam ser duplicados, ou seja, mesma função em métodos distintos. Atrapalhando a manutenção que teria de ser realizada em diversos pontos, o que permitiria deixar algum "esquecido" e tendo um funcionamento errado.

Para o Java existe uma convenção de linguagem oficial ([Conventions for the Java TM Programming Language]), o BISCore recomenda sua leitura e que suas convenções sejam seguidas. Escrever o código como o "mundo" já o faz, facilitará inclusive a ao ler códigos de outros desenvolvedores que já seguem o padrão.


Note 64.png
Formatação de Código Fonte
A formação do código fonte pode ser configurada em muitas IDEs. O BISCore já disponibiliza essas configurações em um arquivo para ser carregado no Eclipse. Como configura-lo pode ser encontrado no tópico de Configuração do Ambiente de Desenvolvimento.


Stop 256.png
SVN e Formatação de Código
A utilização de uma formatação do código diferente entre os desenvolvedores poderá fazer com que o SVN não interprete corretamente as diferenças das alterações, fazendo com que qualquer commit seja uma alteração de arquivo completo. Isso impede o rastreamento de alterações de cada usuário e causa um uso desnecessário de espaço no servidor SVN.


Convenções de Nome do BIS

Adicionalmente o BIS tem suas próprias convenções, as convenções previstas no BIS são mais específicas para o propósito do framework e não conflitem com as definidas pelo próprio Java.

Nomes dos Objetos

Sufixos de Objetos Gerais da Aplicação

  • VO: O sufixo VO é dado aos objetos que representam um determinado objeto/informação. Por exemplo, um objeto que carregue os dados de um contato (como nome, endereço, telefone, RG, etc.) se for batizado de Contact, deve levar o prefixo VO, deixando o nome do objeto como ContactVO.
  • Facade: O sufixo Facade é dado para as classes de Fachada dos módulos. Essas fachadas são usadas para permitir a comunicação de outras camadas com o core do módulo. Normalmente é recomendada apenas uma única fachada por módulo. Mas não é uma regra. Dependendo do módulo o desenvolvedor pode desejar ou precisar ter mais de uma fachada. Lembre-se apenas que quando mais fachadas tiver, mais lookups outros módulos tem de fazer para conseguir chamar diferentes métodos.
  • CorePlugin: Sufixo usado nas classes que implementam um CorePlugin. Esta classe é utilizada para que o BISCore possa interpretar e se comunicar com o módulo.
  • PluginDefinitions: Quando centralizamos as definições do módulo em uma classe separada da classe que implementa as interfaces/adapters que definem o plugin (core, presentation ou integration) damos esse sufixo para facilitar encontra-la quando precisamos atualizar suas definições, como por exemplo a versão.

Sufixos da Camada de Persistência

  • DAO: O sufixo DAO representa Data Access Object e é dado aos objetos que fazem a persistência dos objetos. No padrão do BISFrameWork, DAO só precisa ser criado em casos bem específicos para performance. Leia no tópico da BISDAO.

Sufixos da Camada de Negócio (CRUD)

  • Task: O sufixo Task é dado para as tarefas do BISCore. Tarefas são classes de delegação de função que permitem serem disparadas por outros serviços, como o BISWorkflow ou o BISScheduler. Leia mais no tópico BISTask.

Sufixos das Classes de Relatórios

  • Bean: Termina com Bean a classe que representa um dado retornado pelo relatório. Essa classe é usada no lugar do VO quando o objeto não é "persistível", por exemplo, quando o dado retornado é uma coleção de dados manipulados, somatórias, resumos ou mistura de informações de vários objetos que não permite que o próprio VO seja retornado. Neste caso um Bean é retornado, e tem a mesma estrutura que um VO (atributos e métodos Get e Set).
  • OptionBean: Objeto usado para acumular diversas propriedades de opções e substituir uma coleção enorme de parâmetros nos métodos. Apresenta uma estrutura de Bean, e permite que seja o único parâmetro a ser passado para um determinado método, sendo anexável mais atributos dentro do mesmo objeto com facilidade no futuro.
    • ReportOptionBean: Exatamente o objeto acima, mas quando usado para a geração de relatórios "impressos" (PDFs), cujas classes geradoras levam o prefixo "Report", acabam herdando ambos os prefixos "Report" + "OptionBean".

Métodos e Funções

Alguns métodos muito usados já tem um prefixo definido, verifica abaixo a lista dos prefixos dos métodos o que se espera que um método com esse prefixo faça.

Note 64.png
Prefixos & Sufixos
Alguns métodos também tem sufixos definidos, isso significa que para cada sufixo um método tem alguma variação no seu funcionamento.
  • find: Os métodos de find são específicos para procurar/buscar algum objeto. Geralmente vindo do banco de dados.
  • update: Atualiza um objeto. Este método manipula algum objeto para deixa-lo atualizado. Por exemplo, um método que recebe um VO e o atualiza no banco de dados, ou um método chamado quando ocorre algum evento (Ex: seleção de item pelo usuário) e precisa atualizar alguma informação (Ex: Habilitar/Desabilitar um botão. Note que este método não trata o disparo do evento, mas sim realizar alguma tarefa de atualização de objeto. Para tratar eventos verifique o prefixo 'changed'.
  • change: São métodos de update mais diretos, servem principalmente para atualizar apenas algum atributo do objeto no banco de dados, sem ter que passar ele todo para o core. Assim este método recebe somente um identificador e o novo valor a ser definido no objeto. A ideia por trás deste tipo de método é evitar que o objeto seja todo carregado, e na atualização seja todo re validado perdendo em performance.
  • insert: Métodos chamados para inserir um objeto em algum contexto. Como por exemplo inserir um novo VO no banco de dados.
  • process: Métodos que recebem um objeto e fazem algum processamento ou a partir deles. Costumam retornar o objeto manipulado embora não seja obrigatório, principalmente quando o processamento manipula mais de um método por vez.
  • changed: Como a maior parte dos eventos de apresentação são tratados em anonymous inner classes para evitar a codificação de uma classe só para tratar um evento pequeno, ou desde o Java 8 por expressões Lambda, dentro deste listener colocamos apenas a chamada para um método na classe principal, este método terá o prefixo 'changed'. Exemplo, imagine o um ComboBox chamado 'sector', ao se alterar o valor deste combo chamaremos o método 'changedSectorValue()'. E dentro deste método implementamos o que for necessário.