Комментарии помогают объяснить решение, зафиксировать важное ограничение или описать публичный API. Но комментарий не должен заменять понятные имена и нормальную структуру кода.
Однострочные комментарии
// Основной вариант однострочного комментария
$enabled = true;
# Такой синтаксис тоже поддерживается
$limit = 10;Многострочный комментарий
/*
* Здесь можно разместить
* несколько строк текста.
*/PHPDoc
Документирующие комментарии начинаются с /**. Их используют для описания классов, методов, параметров и возвращаемых значений, особенно если информация не выражается декларациями типов.
/**
* Возвращает отображаемое имя пользователя.
*/
function displayName(string $name): string {
return trim($name);
}Плохой комментарий
// Увеличиваем i на 1
$i++;Такой комментарий повторяет очевидное. Полезнее объяснять почему принято необычное решение, откуда взялось ограничение или с чем связан обходной путь.
Следите за актуальностью
Устаревший комментарий хуже отсутствующего: код меняется, а старое пояснение начинает вводить в заблуждение. При изменении логики проверяйте комментарии рядом с ней.
