Раньше, когда я не пользовался IDE, я частенько бегал в гугл. Держать в голове всю документацию php — нереально, никогда не запомнишь всего и вся. А чтобы найти нужную функцию или класс в доке — нужно: интернет, набрать в гугле запрос, перейти к функции и только после этого начать читать, потом прочитав — вернуться в редактор. В день таких операций может быть десятки, они могут отнимать в день достаточно много времени. Очень много. Если еще посчитать время, которое теряется при отвлечении от кода, то оно может измеряться десятками минут, и даже часами!
Но на подобных операциях можно легко сэкономить время. Достаточно иметь под рукой IDE. Представим типичную ситуацию — вы пишете что-то, вам надо воспользоваться какой-то функцией, например, str_replace(). Как сделаю я в phpStorm — просто зажму ctrl и наведу мышкой на стандартную функцию. Если мне будет недостаточно списка параметров, то я нажму ctrl+Q (или F1 на маке), и мне откроется полная документация по функции с описанием, из которого, если мне надо, я смогу перейти к странице оф. документации
Удобно — не правда ли? Кто-то скажет — дока на английском, не удобно. Я отвечу — учите английский, пригодится 🙂 современному разработчику без английского никуда. Другие IDE, например тот же Netbeans, имеет встроенную русскую справку по стандартным функциям.
Что самое интересное — подобная функциональность возможно благодаря движку phpStorm. Любой phpDoc комментарий будет мгновенно подцеплен, и аналогичным же образом его можно просмотреть при любом вызове функции. Благо, сделать phpDoc комментарий в IDE — дело нескольких секунд:
Набираем /** и жмем Enter — все, самое сложное уже сделано, осталось оставить небольшой коммент.
И теперь вам никакого труда не стоит узнать, какие типы переменных принимает функция, какой тип переменных функция возвращает, можете просмотреть комментарий, оставленный разработчиком к функции. Поверьте — хороший комментарий к большой и сложной функции может сэкономить очень много времени вашему коллеге, да и вам самому через некоторое время.
А документировать с помощью phpDoc можно не только функции. Можете документировать свои константы, например. И в любом месте проекта можете быстренько просмотреть, для чего данная константа нужна
Мораль — документирование реально упрощает жизнь. Не только вам, но и вас окружающим, поэтому берем, и идем на оф. сайт phpDocumentor и изучаем, как должны выглядеть комменты
Что интересно — в phpStorm документация к стандартному php коду сделана по аналогии с тем, как она работает для ваших функций. В ядре продукта есть обычный файл со списком функций, где в phpDoc комментариях для них расписана официальная документация. Вот так то
Спасибо Ивану за «пинок», с его подачи написал
