Блог программиста

О важности комментирования кода говорилось уже много раз. Потому о том, что комментарии помогают и очень нужны программисту мы в тысячный раз говорить не будем. Лучше поговорим о правильном и красивом использовании возможностей phpDoc в замечательной IDE - Eclipse.
Если вы хотите что б каждый класс написанный вами был понятен вам и вашим коллегам - можете использовать довольно простой стандарт записи комментариев, который будет обработан Eclipse и выведен при работе с этим классом или методом:

/**
* Short description - used in indexlists
*
* Multiple line detailed description.
* The handling of line breaks and HTML is up to the renderer.
* Order: short description - detailed description - doc tags.
*
* @param string Target directory for the generated HTML Files
*/

Если перед обьявлением класса или метода написать такой комментарий - IDE обработает его и выведет вам подсказку при дальнейшем их использовании. Это очень удобно при коллективной разработке и больших обьемах кода. Назначение методов становится понятнее, передаваемые параметры выводятся, возвращаемые значения указываются.
Следует отметить что Eclipse автоматически генерирует заготовку под такой стиль комментария после введения /** и нажатия Enter перед обьявлением метода/класса. А получить подсказку можно по нажатию Ctrl+Space после ввода $myClassName->.