Padrões de comentários para repositórios de arquivos

From COREPHP

(material extraído e adaptado de http://www.walkeralencar.com)

Depois de algum tempo trabalhando com repositórios como CVS e SVN, definimos um padrão que facilita a identificação do que foi adicionado, modificado, deletado e quais correções foram efetuadas a cada revisão melhorando o controle de quem fez e quando ocorreu as mudanças, facilitando a geração de changelogs posteriormente.

São apenas 4 ações básicas [ ADD, DEL, UPDATE e FIXED ].

[ADD]

Sempre que adicionar arquivos, métodos em classes, funções, recursos, ou seja, tudo que for novo deverá ser informado.

   [ADD]
   - wsException:
     - Adicionado Método identificador de Código de Erro.
     - Adicionado Método que Obtém o BackTrace.
   - wsMessage:
     - Gerenciamento Mensagens exibidas: Erros, Alertas e Informações.

[DEL]

Sempre que remover arquivos, métodos em classes, funções, recursos, ou seja, tudo que for removido deverá ser informado, para toda remoção deve haver uma justificativa. Seguindo o template: - [O que foi deletado?], [Qual motivo?].

   [DEL]
   - Módulo "teste", depreciado e desnecessário no sistema.
   - Arquivos CSS, desnecessários.
   - Config do login, passou para o config geral.

[UPDATE]

Sempre que melhorar arquivos, métodos em classes, funções, recursos, ou seja, tudo que for melhoria ou Manutenção Evolutiva deverá ser informado.

   [UPDATE]
   - Posicionamento do Menu.
   - Ícone das Mensagens de: Erros, Alertas e Informações.
   - Módulo NovoUsuario:
     - Ajustado ao Code Standards.
     - Finalizado a Documentação.

[FIXED]

Sempre que corrigir arquivos, métodos em classes, funções, recursos, ou seja, tudo que for correção ou Manutenção Corretiva deverá ser informado. Será um patch sempre corrigir algo que funcione, porém, de forma incorreta.

   [FIXED]
   - Corrigido cálculo de frete.
   - Correção no nome dos templates nos módulos: produto e categoria.
   - Corrigido problema na validação do login.

Conclusão

Resumindo o Padrão:

   * Adicionou? ADD.
   * Removeu? DEL.
   * Melhorou? UPDATE.
   * Corrigiu algo? FIXED.