Entendendo Comentários em PHP

Comentários são anotações que você deixa no código-fonte e que o PHP ignora ao executar o programa. Eles existem exclusivamente para humanos — para explicar por que um trecho de código faz o que faz, deixar lembretes ou desativar código temporariamente durante a depuração. Este guia cobre todos os estilos de comentário suportados pelo PHP, quando usar cada um e as práticas que mantêm os comentários úteis em vez de ruído.

Este capítulo pressupõe que você já saiba escrever PHP básico. Caso contrário, comece pelos capítulos PHP Syntax e PHP Variables primeiro.

O que são Comentários PHP?

Um comentário é texto no seu código que o interpretador PHP não executa. Quando o PHP analisa um arquivo, ele pula os comentários inteiramente — eles nunca afetam a saída, o desempenho ou o comportamento. Servem como documentação para quem lê o código depois, incluindo você mesmo no futuro.

O PHP suporta três estilos de comentário, que se dividem em dois grupos:

• Comentários de linha única, escritos com // ou #.
• Comentários multilinha (bloco), escritos com /* ... */.

O PHP herda os estilos // e /* */ do C e do Java, e o estilo # dos scripts de shell e do Perl — portanto, independentemente da linguagem de origem, um deles parecerá familiar.

Comentários de Linha Única

Um comentário de linha única faz o PHP ignorar o restante da linha atual. O PHP oferece dois marcadores intercambiáveis para isso: // (estilo C) e # (estilo shell). Eles se comportam de forma idêntica — escolha um e mantenha a consistência dentro do projeto.

<?php
// This is a single-line comment (C-style)
echo "Hello, world!";

# This is also a single-line comment (shell-style)
echo " Goodbye!";

echo " Done."; // a comment can also follow code on the same line

O comentário termina na quebra de linha, portanto as instruções echo ainda são executadas. O script acima imprime Hello, world! Goodbye! Done.

Comentários Multilinha

Um comentário multilinha começa com /* e termina com */. Tudo entre esses marcadores é ignorado, mesmo que abranja muitas linhas. Use-o para explicações mais longas ou para comentar um bloco de código de uma só vez.

<?php
/* This is a multi-line comment.
   It can span as many lines as you need,
   which is handy for longer explanations. */
echo "Visible output";

/* You can also keep it on a single line */ echo " — still works";

As duas instruções echo imprimem Visible output — still works; tudo dentro de /* ... */ é ignorado.

Atenção — comentários de bloco não são aninhados. O PHP encerra o comentário no primeiro */ que encontrar. Se você envolver código que já contém um comentário /* ... */, o bloco externo termina antes do esperado e o */ restante causa um erro de análise. Para desativar um trecho de código que já possui comentários de bloco, use // ou # em cada linha.

Por que Usar Comentários PHP?

Os comentários PHP são uma ferramenta importante para os desenvolvedores, pois ajudam a tornar o código mais fácil de entender e manter. Ao adicionar comentários ao seu código, você pode explicar o propósito de linhas específicas ou fornecer informações adicionais sobre o código. Isso facilita para outros desenvolvedores entenderem e manterem seu código, e também ajuda você a lembrar o que ele faz ao revisitá-lo mais tarde.

Como Usar Comentários PHP

Para adicionar um comentário ao seu código PHP, basta iniciar a linha com duas barras (para comentários de linha única) ou uma barra e um asterisco (para comentários multilinha). É importante escolher o tipo de comentário adequado com base no tamanho e na complexidade do código que você está comentando.

Também é importante garantir que seus comentários sejam claros e concisos e que forneçam informações significativas sobre o código. Evite usar comentários apenas para repetir o código ou afirmar o óbvio. Em vez disso, concentre-se em fornecer informações que não sejam imediatamente aparentes a partir do código.

Comentando Código Durante a Depuração

Um dos usos mais práticos dos comentários é desativar temporariamente o código sem excluí-lo. Prefixe uma linha com // ou #, ou envolva várias linhas em /* ... */, para retirá-las do programa:

<?php
$total = 10 + 5;
// echo $total;        // disabled: don't print yet
echo "Total calculated";

Lembre-se da regra de não aninhamento acima: se o código que você deseja desativar já contém um bloco /* */, comente-o linha por linha com //.

Comentários de Documentação (PHPDoc)

Além dos comentários simples, o ecossistema PHP possui uma convenção de documentação chamada PHPDoc. É um comentário de bloco que começa com /** (dois asteriscos) e usa tags @ para descrever funções, parâmetros e valores de retorno. IDEs e ferramentas como o phpDocumentor leem esses comentários para fornecer autocompletar e gerar documentação de API.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b)
{
    return $a + $b;
}

echo add(2, 3); // 5

O PHPDoc é tecnicamente apenas um comentário /* */ normal para o interpretador PHP — não tem efeito em tempo de execução — mas seguir a convenção torna suas funções muito mais fáceis de entender para editores e colegas de equipe. Você o verá bastante no capítulo PHP Functions.

Boas Práticas para Comentários PHP

Aqui estão algumas boas práticas a seguir ao usar comentários PHP:

• Use linguagem clara e concisa nos seus comentários
• Evite repetir o código nos comentários — explique o por que, não o o quê
• Concentre-se em fornecer informações que não sejam imediatamente aparentes no código
• Use níveis adequados de detalhamento nos seus comentários
• Mantenha seus comentários atualizados conforme o código evolui — um comentário desatualizado é pior do que nenhum
• Prefira nomes de variáveis e funções autoexplicativos a comentários que expliquem nomes pouco claros

Conclusão

Os comentários PHP são uma ferramenta essencial para desenvolvedores, permitindo tornar o código mais fácil de entender e manter. O PHP oferece três sintaxes — // e # para linhas únicas, e /* ... */ para blocos — além da convenção PHPDoc para documentar funções. Seguindo as boas práticas descritas neste artigo, você pode aproveitar ao máximo os comentários PHP e garantir que seu código esteja bem documentado e fácil de entender para outros desenvolvedores.

Para continuar aprendendo, avance para PHP Variables e PHP Operators.

Prática