Pular para o conteúdo principal

Comentários e Documentação em PHP

Introdução​

Comentários e documentação são elementos essenciais em qualquer projeto de software, facilitando a manutenção e compreensão do código por diferentes desenvolvedores ao longo do tempo. Em PHP, além dos comentários comuns, utilizamos o PHPDoc para documentar classes, propriedades, métodos, e mais, proporcionando uma maneira padronizada de descrever a estrutura e o comportamento do nosso código.

Comentários no Código​

Comentários no código devem ser usados para explicar "por que" algo foi feito, ao invés de "o que" foi feito. O código em si deve ser claro o suficiente para explicar "o que" está acontecendo, enquanto os comentários devem fornecer contexto adicional.

Exemplos de Comentários​

// Calcula o desconto baseado no tipo de cliente
$discount = ($customerType == 'vip') ? 20 : 5;

/* 
Verifica se o usuário tem permissão para acessar
o recurso antes de prosseguir
*/
if (!userHasAccess($user)) {
    return false;
}

Documentação com PHPDoc​

/**
 * Classe para representar um usuário.
 *
 * Esta classe é utilizada para trabalhar com as informações do usuário.
 */
class User
{
    // ...
}

Documentando Propriedades​

/**
 * @var string Nome completo do usuário.
 */
private $name;

Documentando Métodos​

/**
 * Calcula a idade do usuário baseado na data de nascimento.
 *
 * @param string $birthDate A data de nascimento no formato 'YYYY-MM-DD'.
 * @return int A idade calculada.
 */
public function calculateAge($birthDate)
{
    // ...
}

Boas Práticas​

  • Seja conciso: Evite comentários desnecessários que podem ser inferidos pelo código.
  • Mantenha atualizado: Certifique-se de que os comentários e a documentação PHPDoc sejam atualizados conforme o código evolui.
  • Use tags PHPDoc apropriadas: Utilize as tags do PHPDoc, como @param, @return, e @var, para proporcionar informações específicas sobre o código.

Ao seguir essas diretrizes para comentários e documentação em PHP, você garantirá que seu código seja não apenas funcional, mas também fácil de entender e manter.

Conclusão​

Este documento oferece uma visão geral sobre como e onde adicionar comentários ao seu código PHP, além de introduzir o uso do PHPDoc para documentar classes, propriedades, métodos e mais. Ajuste conforme necessário para atender às convenções e necessidades específicas do seu projeto.