PHP Comentários

Um comentário é um texto dentro do código que o PHP ignora completamente. Ele não muda o que o programa faz: serve para as pessoas. Para você mesmo, daqui a três meses, lembrar por que fez daquele jeito; para quem trabalha com você entender o código; e para "desligar" uma linha sem apagá-la. Nesta aula você vai conhecer as quatro formas de comentar no PHP e uma armadilha nova do PHP 8.

A ideia: o lápis na margem do livro

Pense numa receita de bolo da sua avó, com anotações a lápis na margem: "usar a forma grande", "no forno da tia, 10 minutos a menos". Quem faz o bolo lê as anotações; o bolo não "lê" nada. As anotações não mudam a receita, mas ajudam muito quem vai segui-la.

Os comentários são essas anotações. O PHP pula tudo o que está marcado como comentário, como se não existisse. Quem lê é gente.

Comentários de uma linha: // e #

Duas barras // dizem ao PHP: "daqui até o fim da linha, ignore". O # (cerquilha, "jogo da velha") faz exatamente a mesma coisa:

<?php
// Programa da lista de compras da Ana
echo "Lista de compras\n"; // título

# Este também é um comentário de uma linha
echo "- pão\n";

$ php tipos.php
Lista de compras
- pão

// Programa da lista…

Um comentário ocupando a linha inteira. O PHP pula.

echo "Lista de compras\n"; // título

Código e depois um comentário, na mesma linha. O PHP executa o echo e ignora o que vem a partir do //.

# Este também…

Mesmo efeito, com #.

Repare na saída: nenhum comentário apareceu. Eles existem só no arquivo.

Dentro de um texto, não é comentário

As marcas de comentário só valem no código. Dentro de aspas, // e # são caracteres comuns. Ainda bem: senão, nenhum endereço https:// funcionaria.

<?php
echo "Site: https://www.php.net // não é comentário\n";
echo "# também não\n";

$ php string.php
Site: https://www.php.net // não é comentário
# também não

Comentários de várias linhas: /* … */

Para um texto mais longo, abra com /* e feche com */. Tudo o que estiver entre as duas marcas é ignorado, quantas linhas forem:

<?php
/*
   Comentário de várias linhas:
   o leite acabou, mas o café ainda tem.
*/
echo "- leite\n";

$total = 10 /* preço */ * 2;
echo "Total: $total\n";

$ php bloco.php
- leite
Total: 20

/*

Abre o comentário. Pode estar sozinho na linha ou junto do texto.

*/

Fecha. Tudo entre /* e */ some para o PHP.

10 /* preço */ * 2

Como o bloco tem começo e fim marcados, ele pode ficar até no meio de uma linha de código. O PHP lê 10 * 2. Funciona, mas atrapalha a leitura: use com moderação.

É comum ver blocos com um * no começo de cada linha, só por estética:

<?php
/*
 * Lojinha da Ana
 * Versão 1, outubro de 2026
 */

Os * do meio não têm função nenhuma: são parte do texto do comentário. Só o /* do começo e o */ do fim importam.

Comentários de documentação: /** … */ (PHPDoc)

Um bloco que começa com dois asteriscos, /**, é um comentário de documentação, no formato chamado PHPDoc. Para o PHP, ele continua sendo um comentário: não muda nada na execução. A diferença é que os editores de código e outras ferramentas sabem ler esse formato.

Ele é usado logo acima de algo que se quer documentar, como uma função (você vai aprender a criar funções no Nível 2; aqui basta saber que total calcula preço vezes quantidade):

<?php
/**
 * Calcula o total de uma compra.
 *
 * @param float $preco Preço de uma unidade.
 * @param int   $qtd   Quantidade comprada.
 * @return float O preço vezes a quantidade.
 */
function total(float $preco, int $qtd): float
{
    return $preco * $qtd;
}

echo total(12.5, 3), "\n";

$ php doc.php
37.5

/**

Abre um comentário de documentação (dois asteriscos).

Calcula o total de uma compra.

A primeira frase: um resumo do que vem abaixo.

@param float $preco …

Uma etiqueta (tag): começa com @. @param descreve um parâmetro, a informação que a função recebe: o tipo, o nome e o que ele significa.

@return float …

Descreve o que a função devolve.

*/

Fecha, como num bloco comum.

Para que serve, se o PHP ignora? Quando você passa o mouse sobre total( em outra parte do código, editores como o VS Code e o PhpStorm mostram esse texto numa caixinha, com a descrição de cada parâmetro (veja Editores e IDEs). Ferramentas como o phpDocumentor transformam esses comentários num site de documentação. As etiquetas mais vistas:

No PHP moderno, os tipos podem ficar no próprio código (o float $preco e o : float do exemplo; veja Tipos e Retorno), e o PHPDoc fica para as explicações. Enquanto você aprende, não precisa documentar tudo; basta reconhecer o formato quando encontrá-lo.

<?php
$preco = 12.5;
$qtd = 3;
echo "Depuração: preço = $preco\n";
echo "Total: ", $preco * $qtd, "\n";

<?php
$preco = 12.5;
$qtd = 3;
// echo "Depuração: preço = $preco\n";
echo "Total: ", $preco * $qtd, "\n";

"Comentar" uma linha para desligá-la é um truque que você vai usar o tempo todo para encontrar defeitos (veja Depurar). Nos editores de código, o atalho Ctrl+/ coloca ou tira o // da linha onde está o cursor, ou de todas as linhas selecionadas.

Cuidado: #[…] não é comentário PHP 8.0+

Até o PHP 7, qualquer coisa começando com # era comentário. No PHP 8 surgiram os atributos, um recurso que "etiqueta" funções e classes, e eles são escritos justamente com #[ … ]. Resultado: uma "anotação" que começa com #[ deixou de ser comentário e virou código:

<?php
#[TODO] colocar o preço
echo "Olá!\n";

$ php attr.php

Parse error: syntax error, unexpected identifier "colocar" in /home/ana/coment/attr.php on line 2

O PHP leu #[TODO] como um atributo chamado TODO e depois achou a palavra solta colocar, que não faz sentido ali. Com um espaço entre o # e o [, volta a ser comentário:

<?php
# [TODO] colocar o preço
echo "Olá!\n";

$ php attr2.php
Olá!

E o pior caso é quando não dá erro. Se o #[…] estiver logo acima de uma função, ele é um atributo válido, e o PHP aceita calado:

<?php
#[TODO]
function saudar() {
    echo "Olá!\n";
}
saudar();

$ php attr4.php
Olá!

Aqui nada quebrou, mas o #[TODO] não é uma anotação para você: é código, que o PHP guardou como um atributo da função. Os atributos de verdade têm usos importantes, como o #[\Override] e o #[\Deprecated], e são assunto de Atributos.

<?php
#[TODO] mostrar o preço com vírgula
echo "Preço: R$ 12.5\n";

<?php
// TODO: mostrar o preço com vírgula
echo "Preço: R$ 12.5\n";

Mais duas armadilhas

O ?> fecha o PHP, mesmo dentro de //

A marca ?> encerra o trecho de PHP e volta ao "modo HTML" (veja PHP Dentro do HTML). Ela é tão forte que termina um comentário de uma linha:

<?php
echo "Antes\n";
// o PHP termina com ?> e volta ao HTML
echo "Depois\n";

$ php fecha.php
Antes
 e volta ao HTML
echo "Depois\n";

O comentário acabou no ?>. Dali em diante, o PHP estava fora do modo PHP: o resto da linha e o echo de baixo saíram como texto comum, e o "Depois" nunca foi executado. Num comentário de várias linhas (/* … */), o ?> não tem esse efeito. Se precisar escrever ?> num comentário, use um bloco /* */.

Um /* */ não cabe dentro de outro

O comentário de bloco termina no primeiro */ que aparecer. Por isso não dá para "aninhar" (colocar um dentro do outro). Isso pega quem tenta desligar um trecho que já tinha um comentário de bloco:

<?php
/*
echo "pão\n";
/* echo "leite\n"; */
echo "café\n";
*/
echo "fim\n";

$ php aninhado.php

Parse error: syntax error, unexpected token "*", expecting end of file in /home/ana/coment/aninhado.php on line 6

O primeiro */ (linha 4) fechou o comentário. A linha 5 virou código de novo, e o */ da linha 6 sobrou, sem par. Para desligar trechos grandes, prefira // em cada linha (o Ctrl+/ faz isso por você).

Comentários no PHP × comentários no HTML

Numa página web você pode usar dois tipos de comentário, e eles têm destinos diferentes:

<!DOCTYPE html>
<html>
<body>
<!-- Comentário HTML: o visitante vê no código-fonte -->
<?php
// Comentário PHP: o visitante nunca vê
$nome = "Ana";
/* Este também não sai do servidor */
echo "<p>Olá, $nome!</p>\n";
?>
</body>
</html>

O que chega ao navegador (pelo servidor embutido):

$ curl -s localhost:8000/index.php
<!DOCTYPE html>
<html>
<body>
<!-- Comentário HTML: o visitante vê no código-fonte -->
<p>Olá, Ana!</p>
</body>
</html>

O comentário HTML <!-- … --> está fora do PHP, então é texto comum e vai para o navegador. Ele não aparece na página, mas qualquer pessoa vê com "Exibir código-fonte". Os comentários PHP ficam no servidor. Por isso, nunca escreva senhas, nomes de servidores ou detalhes internos em comentários HTML.

O que escrever num comentário

Comentário bom explica o porquê; o quê, o próprio código já diz. Compare:

Enquanto você aprende, porém, vale o contrário: comente à vontade, até o óbvio. Escrever em português o que cada linha faz é um ótimo jeito de estudar. Só não estranhe quando, em projetos profissionais, os comentários forem poucos e bem escolhidos.

Quando dá errado

$ php attr.php

Parse error: syntax error, unexpected identifier "colocar" in /home/ana/coment/attr.php on line 2

<?php
echo "Olá\n";
/* comentário que nunca fecha
echo "Tchau\n";

$ php naofechou.php

Parse error: Unterminated comment starting line 3 in /home/ana/coment/naofechou.php on line 3

$ php aninhado.php

Parse error: syntax error, unexpected token "*", expecting end of file in /home/ana/coment/aninhado.php on line 6

$ php fecha.php
Antes
 e volta ao HTML
echo "Depois\n";

<?php
function total(float $preco, int $qtd): float
{
    return $preco * $qtd;
}

echo total(12.5, 3), "\n";

<?php
/**
 * Calcula o total de uma compra.
 *
 * @param float $preco Preço de uma unidade.
 * @param int   $qtd   Quantidade comprada.
 * @return float O preço vezes a quantidade.
 */
function total(float $preco, int $qtd): float
{
    return $preco * $qtd;
}

echo total(12.5, 3), "\n";

Referência

Exercícios

Resumo

• Comentários são ignorados pelo PHP; servem para pessoas.
• // e #: até o fim da linha. Prefira //.
• /* … */: várias linhas, até o primeiro */; não dá para colocar um dentro do outro.
• /** … */ (PHPDoc): documentação com etiquetas como @param e @return, lida por editores e ferramentas.
• No PHP 8, #[…] é um atributo, não comentário.
• Um ?> dentro de // encerra o PHP. Dentro de aspas, // e # são texto comum.
• Comentar uma linha (Ctrl+/) é o jeito de desligá-la sem apagar.
• Comentários HTML vão para o navegador; comentários PHP ficam no servidor.