A cartilha do “bom programador” sempre prega que para manter seu código padronizado e legível precisa-se sempre utilizar linhas de comentários para auxílio próprio ou mesmo para que terceiros entendam facilmente sua implementação e possam dar continuidade a ela. Quanto maior o sistema, maior o número de linhas de código e consequentemente maior a complexidade. Para “digerir” melhor essa complexidade o bom uso de comentários é fundamental.
E para comentar um código de forma padronizada e organizada nós temos algumas regras, que apesar de serem relativamente simples, podem ajudar bastante no processo de documentação de códigos.
Existem algumas tags especiais que devem ser utilizadas nas marcações de comentários e sempre iniciadas por arrobas(@). Essas tags servem para caracterizar uma determinada classe ou método. Veja um exemplo:
1 2 3 4 5 6 7 8 9 10 | <?php /** * Classe para auxiliar cálculos matemáticos * * @author Rafael Wendel Pinheiro * @version 1.0 */ class Matematica { } |
Coloquei algumas informações antes de iniciar a implementação da classe. Uma breve descrição sobre a mesma, o autor e sua versão. Vejamos agora um exemplo de documentação de um método:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | <?php /** * Classe para auxiliar cálculos matemáticos * * @author Rafael Wendel Pinheiro * @version 1.0 */ class Matematica { /** * Método para somar dois números * @author Rafael Wendel Pinheiro * @access public * @param int $numero1 O primeiro número * @param int $numero2 O segundo número * @return int $resultado O resultado da soma dos números */ public function soma($numero1, $numero2){ $resultado = $numero1 + $numero2; return $resultado; } } |
Percebam que coloco uma descrição do método soma para que se saiba o seu objetivo e depois coloco o tipo de acesso (pode ser public, private ou protected). A propriedade @param serve para abordar os parâmetros que o método deve receber como entrada e o @return para descrever o que será retornado por ele.
Veja algumas das tags especiais que podemos utilizar na documentação de um código:
- @access Específica o tipo de acesso(public, protected e private).
- @author Específica o autor do código/classe/função.
- @copyright Específica os direitos autorais.
- @deprecated Específica elementos que não devem ser usados.
- @exemple Definir arquivo de exemplo, $path/to/example.php
- @ignore Igonarar código
- @internal Documenta função interna do código
- @link link do código http://www.exemplo.com
- @see
- @since
- @tutorial
- @name Específica o apelido(alias).
- @package Específica o nome do pacote pai, isto ajuda na organização das classes.
- @param Específica os paramêtros muito usado em funções.
- @return Específica o tipo de retorno muito usado em funções.
- @subpackage Específica o nome do pacote filho.
- @version Específica a versão da classe/função.
Uma classe bem comentada/documentada auxilia quem irá utilizá-la já que a maioria das ferramentas editoras de códigos e IDEs oferecem a opção de auto-complemento e nessa funcionalidade é o que está comentado que irá aparecer para o programador. Veja um print da chamada dessa classe (IDE: NetBeans 6.5):
Com isso é possível também gerar a documentação de um projeto através de ferramentas como o PHPDoc.
Espero que lhe seja útil.
Abs.
Siga-me no twitter: @rafaelwendel
Rafael Wendel Pinheiro
É formado em Sistemas de Informação, pós-graduado em Sistemas de Banco de Dados e mestre em Educação com foco em Tecnologias Sociocomunitárias. Trabalha como professor de ensino técnico e tecnológico no Instituto Federal de Educação, Ciência e Tecnologia de São Paulo ministrando disciplinas nas áreas de programação, banco de dados, desenvolvimento de projetos e engenharia de software.
