PHP Lang
  1. PHP Lang
  3. Наиболее распространенный / любимый синтаксис для документации внутри кода (комментарии)?
Intereting Posts
Как я могу запросить использование внешнего ключа в MySQL? Изменение имени файла tmp, загруженного через форму iCalendar .ics принять / отклонить iOS Функция MACD Возвращает неправильные значения MySQL: mysql_fetch_assoc (): предоставленный аргумент не является допустимым ресурсом результата MySQL Сохранить позицию JQuery DragGable DIVs, используя php Как удалить повторяющиеся строки из файла CSV? Каков тип данных facebook userid Модули Zend Framework с общими ресурсами Недействительная регистрация как на C2DM, так и на GCM Установка WAMP Curl Многоуровневое меню с PHP / MySQL Оценить перенаправление PHP 404, связанное с неверным запросом на получение Различные фоновые изображения CSS в зависимости от месяца и года Примечание. Неопределенная переменная: captcha в C: \ wamp \ projects \ ServiceAdmin \ login \ loginauth.php в строке 11

Наиболее распространенный / любимый синтаксис для документации внутри кода (комментарии)?

Я уже много лет программировал PHP с помощью Notepad ++, но сегодня я загрузил Eclipse IDE. Одной из его особенностей является автоматическое заполнение определенных «синтаксических шаблонов», таких как комментарии. Я видел много разных способов реализации комментариев и документации в php-файлах, поэтому теперь я начал задаваться вопросом, должен ли я следовать синтаксису, который предлагает Eclipse.

Вот что я имею в виду:
введите описание изображения здесь

Как вы думаете?

Мартти Лейн

это формат phpdoc, способ автоматического документирования вашего кода с помощью комментариев.

http://www.phpdoc.org/

По-видимому, Eclipse собирает phpDoc (возможно, самое распространенное решение для проектов PHP и одно, которое я очень рекомендую), которые являются отличным способом документирования различных классов, методов, аргументов метода и т. Д., А также предоставления средств отслеживания дел, маркировки функций / методов как устаревшие и т. д.

Кроме того, вы можете, конечно, генерировать документацию в формате HTML, PDF, CHM и т. Д., Используя инструмент командной строки phpdoc

Вы можете узнать больше (и проверить требуемый синтаксис) на сайте phpDoc .

Eclipse будет лучше использовать комментарии heredoc / phpdoc, которые затем могут быть скомпилированы в документацию. Попробуйте написать функцию, а затем поставить над ней комментарий / **, и вы увидите, что ecplise автоматически добавляет параметры функции в комментарий.

Если вы посмотрите на Java API, это тот тип документации, который получается скомпилированным из этого стиля комментариев.

Если вы не думаете, что когда-либо собираетесь компилировать свои комментарии в документы, то не чувствуете себя связанными им, и дополнительные комментарии в коде всегда полезны. Тем не менее, это стандарт документации, так что это неплохо. Я только склонны использовать этот стиль комментариев для вещей, которые, как я знаю, многие другие люди будут оглядываться.

Как отмечают другие, использование таких комментариев для phpdoc может быть очень ценным. Но я думаю, что это не только генерация документации, но и облегчение написания кода. Некоторые IDE (по крайней мере, Netbeans) используют комментарии phpdoc для обеспечения более качественных функций автозаполнения, чем в противном случае.