Skip to main content
correção ortográfica
Fonte Link

A regras de apresentação do código na PSR-2 se aplicam a DocBlocks, fora isso existe apenas um rascunho em desenvolvimento que poderá vir sea ser uma recomendação no futuro. Pode ser lido aqui: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

A regras de apresentação do código na PSR-2 se aplicam a DocBlocks, fora isso existe apenas um rascunho em desenvolvimento que poderá vir se uma recomendação no futuro. Pode ser lido aqui: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

A regras de apresentação do código na PSR-2 se aplicam a DocBlocks, fora isso existe apenas um rascunho em desenvolvimento que poderá vir a ser uma recomendação no futuro. Pode ser lido aqui: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

Fonte Link

O que é PHPDoc?

Para não confundir aqui vou usar o termo DockBlock alguns vão chamar de doclet ou PHPDoc, isso não importa, o que é importante é diferenciar o PHPDoc comentário do PHPDoc ferramenta.

O PHPDoc ferramenta gera documentação automaticamente com base no código e em comentários DockBlock. Porém você pode usar outras ferramentas para gerar essa documentação, eu particularmente prefiro o ApiGen.

O DockBlock começa com /** , eles tem origem no javadoc e podem (ou não) ter uma infinidades de tags que começam com @;

Qual sua utilidade?

Docblocks são um meio de comunicação entre quem faz o código e quem o consome. Quando você passa seu código para terceiros, ou obtêm um código essa documentação vai ajudar no entendimento, uso e modificação do mesmo.

Eles servem de base para gerar uma documentação objetiva que pode abordar uma série de questões comuns a quem consome o código.

Posso utilizar livremente o código em meus projetos? (@license); Quem é o autor do código? (@author); O que essa função retorna? (@return); etc;

Essas tags se comunicam bem com a máquina elas ajudam o IDE a entender o código, no site do PHPDoc existe uma lista de tags são suportadas pelas ferramentas de geração de documentação.

Existem também frameworks como o Doctrine e PHPUnit que aceitam suas próprias tags nesses comentários. Com elas é possível, por exemplo, mapear e gerar todo o banco de dados ou entidades de uma aplicação com o Doctrine mas esse uso já foge da questão de documentação.

Como usar?

Dentro da filosofia de Robert C. Martin a regra básica que recomendo é: coloque o mínimo possível de comentários mas o suficiente para ser claro.

A exceção é se você vai disponibilizar o código publicamente então - a exemplo dos sistemas open sources mais comuns em PHP - quanto mais explicado melhor, fora este caso raramente vale a energia documentar muito.

Lembre-se que você vai ter manter os comentários coerentes com o código, é muito comum o código ser refatorado e os comentários passarem informações erradas por estarem defasados, por isso muitos consideram comentários como um tipo de duplicação de código.

Qualquer código, função, variável, classe, devem ser claros o suficientes para entendermos o eles fazem e são dentro do seu contexto, sem precisarmos de nenhum comentário explicando.

Quando não atingimos esse ideal um comentário é bem-vindo. Ele pode ser um alerta, esclarecimento ou explicação. Mas esses comentários são sempre fracassos da nossa capacidade de se expressar através do código.

Quando necessário ele deve ser preciso e claro para não confundir, um comentário ruim mais atrapalha do que ajuda.

Existem muitas tags no padrão phpdoc, mas não considero que seja ideal manter a maioria dessas informações em um DocBlock, quando estão nele costumam ser apenas firulas. Autoria, versão, modificação, por exemplo ficam melhor em um sistema de controle versão. Outros exemplos de comentários ruins são aqueles óbvios ou redundantes em relação ao código, são apenas poluição.

Exemplo de documentação inútil:

/**
* Entidade Usuário
*/
class user {
    /**
    * nome do usuário
    */
    $nome;

    //...

    /**
     *Estabelece o Nome do usuário
     */
    function setName(){//... }

    /**
     *Pega o Nome do usuário
     */
    function getName(){//... }

    // … 

}

O que vale a pena documentar normalmente são os tipos retornados pelas funções, tipos das variáveis, e tipos dos parâmetros. Mesmo assim só documente quando não é possível a indução (Com PHP 7 a necessidade de documentação deve diminuir). Isso facilita bastante a vida.

Tem alguma regra, recomendação do PSR sobre isso? Se sim, qual?

A regras de apresentação do código na PSR-2 se aplicam a DocBlocks, fora isso existe apenas um rascunho em desenvolvimento que poderá vir se uma recomendação no futuro. Pode ser lido aqui: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md