Возможно, я сейчас буду писать очевидные вещи, но Вы уж простите дорогие мои читатели.
А речь пойдет о самой важной части любой программы – о комментариях.
Грамотно написанный комментарий продлевает жизнь разработчика. Точнее не дает ее потратить на разбирательства в стиле “как же эта хрень работает”. Кроме того, этот самый комментарий неплохое подспорье для среды разработки в деле помощи разработчику.

В качестве примера рассмотрим, как NetBeans обрабатывает некоторые комментарии.
Возьмем классический синглтон Core, который имеет статический метод getInstance() возвращающий экземпляр синглтона.
Но вот только одна беда. IDE спотыкается на Core::getInstance()-> автодополнение молчит как партизан и не признается, какие методы у класса. Этот недостаток, легко исправляется комментарием.

/**
* Return instance of Core class.
*
* @return Core instance of class.
* @access public.
*/

Указав в строчке @return тип Core мы однозначно определеяем для IDE тип возвращаемого значения, чем в дальнейшем будет пользоваться среда, помогая нам не запутаться в методах, свойствах и прочем обвесе класса.
Добавляя в комментарий строчки @param тип $имя_переменной мы информируем среду о том какие параметры ожидает данная функция, что положительно сказывается на работе автодополнения.
Пример:
/**
* Assigns values to template variables.
*
* @param string $name the template variable name.
* @param mixed $value the value to assign.
* @param int $preserve flag that protect var from 'clear' method
* @access public.
*/

В этом случае при наборе имени метода, мы получим точное описание параметров.
Ну и напоследок парочка очень полезных комментариев, которые IDE “понимает”.
// TODO: Не забыть
// FIXME: Срочно поправить
Не забывайте написать их, а среда уж не забудет Вам напомнить.