Se trabalhas ou trabalhas-te com PHP, certamente já te cruzas-te com o PHPDoc. Muitas vezes é algo chato de fazer, mas é uma mais valia. Esta mais valia aumenta o seu valor, quando temos projetos extensões, com muitos ficheiros e linhas de código.
Vamos então perceber o que é o PHPDoc, e em que nos pode ajudar durante e depois do desenvolvimento.
O que é o PHPDoc?
O PHPDoc ou PHPDocumentator, é uma ferramenta baseada no JAVADoc que tem como objetivo padronizar a documentação dos códigos PHP. Esta ferramenta lê todo o código do projeto, procurando por tags expecificas e a partir destas, pode gerar documentação em vários formatos.
Essas tags são adicionadas dentro de comentários em PHP, e é necessário que todas elas sejam iniciadas por @:
Esta documentação que fica dentro do comentário, é chamada de DocBlock.
Para que serve?
Para mim esta ferramenta tem dois objetivos principais (dentre outros):
O primeiro é que a documentação em PHPDoc, vai facilitar a passagem do código a terceiros. Não apenas a terceiros, mas mesmo dentro da equipa, ou equipas do mesmo projeto.
Vamos imaginar o seguinte cenário. Existe um MVP (Produto Mínimo Viável), que depois de desenvolvido, é entregue a uma outra equipa que irá continuar ou integrar o mesmo dentro doutro sistema. Assim que a nova equipa recebe o MVP, e começa o novo desenvolvimento sobre esta base, necessitará de entender o mesmo.
Tendo esta documentação disponível, é mais prático iniciar um teste ou desenvolvimento.
O segundo ponto, é que permite também ao IDE, e extensões em uso no mesmo, que consigam ler o código e transmitir a informação de classes e método de forma mais prática. Isto economiza tempo, e permite uma fluidez bem maior no desenvolvimento.
Como usar?
“Coloque o mínimo possível de comentários, mas o suficiente para ser claro.”
Robert C. Martin
Numa opinião profissional e própria, deve sempre existir documentação. Existem algumas excepções, mas estas devem ser pontuais ou passaram rapidamente a regras.
Se estivermos a desenvolver um projeto pessoal, que apenas nós iremos ter acesso, basta manter algumas notas pontuais durante o projeto, para coisas especificas. Quando entramos em projetos mais complexos, com equipas maiores, deve ser mantido uma documentação limpa e coerente. Isto também deve ser regra, quando disponibilizamos o código a terceiros, como é o caso de projetos open source.
Um exemplo básico de uma documentação mínima, é deixar uma breve descrição desse método, parâmetros do método, os seus tipos e o retorno:
Algumas tags especiais:
- @access – Especifica o tipo de acesso (public, protected e private).
- @author – Especifica o autor do código/classe/método.
- @copyright – Especifica os direitos autorais.
- @deprecated – Especifica elementos que não devem ser usados.
- @exemple – Definir arquivo de exemplo, $path/to/example.php
- @ignore – Ignora código
- @internal – Documenta função interna do código
- @link – Link do código
- @see – Define uma referência a outro elemento ou uma URI
- @since – Define a partir de qual versão os elementos estruturais foram disponibilizados
- @name – Especifica o nome/alcunha (alias).
- @package – Especifica o nome do pacote pai, isto ajuda na organização das classes.
- @param – Especifica os parâmetros (muito usado em métodos).
- @return – Especifica o tipo de retorno (muito usado em métodos), presente no exemplo acima.
- @subpackage – Especifica o nome do pacote filho.
- @version – Especifica a versão da classe/método.
