Недавно я создал CMS для клиента, который предназначен для работы из коробки. Но я допустил ошибку, не комментируя свой код на момент написания. Просто хотел узнать, есть ли инструмент, который будет проходить через файлы CMS и автоматически добавлять блоки комментариев.
Предположим, у меня есть этот код:
class foo{ function bar(array $array){ print_r ($array); } } Инструмент должен иметь возможность комментировать его как ( или несколько похожий ):
class foo{ /** * bar * * @access public * @param array * @return void */ function bar(array $array){ print_r ($array); } }
Редактировать:
Инструмент должен только добавлять заглушки phpdoc, я сам буду писать объяснительные комментарии.
Хотя я уверен, что есть инструменты, которые могут отражать подпись (и, в меньшей степени, токенизировать тело метода), я уверен, что нет инструмента, который мог бы вставить краткое или длинное описание метода . Подумайте об этом, вот где вы – разработчик – описываете, что должна делать функция.
Поэтому, даже если есть инструмент, который может вставлять заглушки, вам все равно придется проходить каждый комментарий. И в этом случае вы можете использовать IDE, например Zend Studio, Eclipse с PDT или Netbeans, чтобы вставить блоки комментариев. Они будут вставлять заглушки при открытии нового блока комментариев автоматически, поэтому все, что вам нужно сделать, это заполнить описание.
Комментарии полезны только в том случае, если они добавляют что-то, чего нет в коде. Конечно, есть инструменты, которые могли бы добавить phpdoc, как ваш пример, но без ручного усилия они не добавят никакой ценности вообще. Написание хороших комментариев почти так же сложно, как писать хороший код, возможно, еще сложнее; на самом деле, хорошие комментарии (наряду с кратким наименованием и надлежащим последовательным отступом) часто отличает хороший поддерживаемый код от бесполезного мусора.
Вы просто не делали домашнее задание, если хотите, так что теперь вам нужно сделать все сразу. Это означает, что вам придется вручную выполнить свой код и добавить комментарии самостоятельно; хорошая IDE будет очень полезной для этого (например, Netbeans может автоматически генерировать phpdoc-заглушки для вас), но фактический комментарий зависит от вас.
У меня был небольшой инструмент, который превратил мой уродливый стиль комментариев в блоки phpDoc. Оглядываясь назад, он кодируется уродливым, будет осторожно запускать его на другом коде (зависит от стиля подписи C), и я даже не помню, почему он так называется crw . Однако он добавляет некоторые шаблоны @param и угадывает типы параметров из нескольких общих имен переменных. Так что никакой замены для ручного пост-редактирования.
Кстати, я всегда задавался вопросом, почему phpDoc не имеет что-то вроде @output. Вышеупомянутая функция примера является пустой, так что не имеет смысла документировать, что она печатает что-то?