Dicas para documentação de códigos PHP

Introdução

Olá, Neste breve artigo, selecionei algumas dicas referente a documentação de códigos voltado para a linguagem PHP. O mais interessante que gostaria de destacar aqui é o PHPDoc. Nomeado como PSR-5: PHPDoc, PSR que ainda consta com o status Draft durante a escrita deste artigo, criada para ajudar na padronização de documentação de códigos PHP (Veja abaixo sobre DocBlocks). Além disso, selecionei algumas dicas genéricas a respeito de documentação de código, que podem ser aproveitadas em qualquer linguagem de programação (Veja abaixo sobre Dicas de Documentação).

DocBlocks

“DockBlocks”, assim como é referenciada na PSR-5, é uma seção (bloco) de comentário que provê informações sobre os aspectos de um determinado bloco de código na linha subsequente.
O que deve conter um “DocBlock” basicamente: Descrição ou Propósito do código, argumentos, valores de retorno, disparo de Exceptions, entre outros dependendo do contexto. Veja abaixo um exemplo básico de DocBlock:

/**
 * This is a Summary.
 *
 * This is a Description. It may span multiple lines
 * or contain 'code' examples using the _Markdown_ markup
 * language.
 *
 * @see Markdown
 *
 * @param int        $parameter1 A parameter description.
 * @param \Exception $e          Another parameter description.
 *
 * @\Doctrine\Orm\Mapper\Entity()
 *
 * @return string
 */
function test($parameter1, $e)
{
    ...
}

Muitas já perceberam a semelhança com o phpDocumentor, não ?. Sim, A PSR-5 é derivado do padrão do phpDocumentor 1.x, com a intenção de prover suporte para novas funções do PHP e para corrigir deficiências do seu antecessor.

De acordo com a definição da PSR, a coleção de construtores abaixo, chamados de “Structural Element”, DEVEM ser precedidos por um DocBlock:

  • file
  • require(_once)
  • include(_once)
  • class
  • interface
  • trait
  • function (including methods)
  • property
  • constant
  • variables, both local and global scope

Na PSR você encontrará muitas outras sugestões, o que DEVE, o que NÂO DEVE ser documentado, entre outras tips. Quais as tags possíveis, etc. O Objetivo é tornar comum um,padrão de documentação entre os projetos, facilitando a leitura do seu código entre os demais desenvolvedores. Elevando dessa forma a qualidade dos projetos escritos em PHP.

Dicas de documetanção

Segue abaixo algumas outras dicas de documentação de códigos que acho válido levar em consideração.

  • Não comente fatos óbvios que podem ser facilmente entendidos apenas verificando o próprio código.
  • Registre pensamentos importantes que teve durante a programação do código. Acredite, é fácil esquecê-los em pouco tempo.
  • Coloque-se na posição de um programador que esteja vendo seu código pela primeira vez. Que tipo de informação seria importante documentar para que o código se torne mais legível ?
  • Procure utilizar palavras que carreguem o máximo de significado afim de tornarem seus comentários mais breves.
  • Use comentários embutidos tornando as chamadas de função/métodos mais legíveis. Ajuda muito principalmente em métodos que recebem vários parâmetros. Exemplo:
  • <?php
    $con = connect($ip, $porta, /* use_crypt = */ true);
    
  • Alerte sobre possíveis problemas e necessidade de futuras implementações em seu código usando comentários com nomenclaturas como TODO: ou FIXME:

Referências


A Arte de Escrever Programas Legíveis

PSR-5

Please follow and like us:

No Responses

Follow

Get every new post on this blog delivered to your Inbox.

Join other followers: