Лучший способ документировать код AJAX + PHP?

Я всегда был для документирования кода, но когда дело доходит до AJAX + PHP, это не всегда легко: код действительно распространен! Логика, данные, презентация - вы называете ее - разделяются и смешиваются между серверным и клиентским кодом. Иногда также используется код базы данных (хранимые процедуры, представления и т.д.), Выполняющие часть работы.

Это бросает мне вызов, чтобы найти эффективный способ документировать такой код. Я обычно предоставляю список файлов .js внутри .php файла, а также список .php файлов внутри .js файла. Я также делаю встроенные комментарии и описания функций, где я перечисляю, какая функция используется каким файлом и какой результат ожидается. Я выполняю аналогичные задачи для процедур базы данных. Может быть, есть лучший метод?

Любые идеи или переживания?

Примечание. Этот вопрос применим к любым клиентским + серверным приложениям, а не только к Javascript + PHP.

Ответы

Ответ 1

Я думаю, что лучше всего взять иерархический подход.

Для документации уровня api, например, на уровне функции и класса, напишите встроенную документацию в коде и выпишите из нее документацию html с помощью многих инструментов документации (JSDoc, phpDocumentor, OraDoclet и т.д.). Бонусные очки, если ваши инструменты doc могут интегрироваться с вашими инструментами управления версиями, чтобы вы могли перейти к определенным строкам кода из своих api docs.

После того, как у вас есть инструменты для документов, начните генерировать документацию как часть процесса сборки (у вас есть процесс сборки, правильно?) для каждой новой сборки и нажмите документацию на стандартное веб-расположение.

После того, как эти api docs находятся в режиме онлайн, вы можете создать вики для документации высокого уровня, например, взаимодействия между браузерами, веб-сайтами, историями пользователей, схемами диаграмм и т.д. Лучше всего писать в краткой прозе или пунктах для высоких документация уровня, связанная с api docs и контролем источника при необходимости.

Ответ 2

Я думаю, что ваш метод довольно хорош. Единственное, что все внутри js файла читается другими, и поэтому документирование того, какие файлы PHP используются, может привести к дыре в безопасности, в противном случае они могут попасть в файл, который возвращает что-то, чего он не должен. Кроме того, хотя это и не очень важно, на более высоких сайтах трафика, загрузка, скажем, 500 байт комментариев может быть добавлена.

Оба они не большие, а просто мысли, которые я имел раньше.

Ответ 3

Предоставляйте свои javascript (и css) через PHP - вы можете хранить исходные файлы для упрощения перекрестных ссылок и при тщательном использовании заголовков вы можете легко справиться с кэшированием. Это также позволяет вам иметь красивую форматированную версию с большим количеством комментариев, которую вы можете затем конденсировать или обфускать перед отправкой в браузер.

function OutputJs($Content) {
    ob_start();
    echo $Content;
    $expires = DAY_IN_S;
    header("Content-type: x-javascript");
    header('Content-Length: ' . ob_get_length());
    header('Cache-Control: max-age='.$expires.', must-revalidate');
    header('Pragma: public');
    header('Expires: '. gmdate('D, d M Y H:i:s', time()+$expires).'GMT');
    ob_end_flush(); 
}

Ответ 4

Для проектов с большим количеством javascript я использую систему сборки (make файлы) с javascript minimizer. Как отмечает автор jsmin, снятие комментариев "поощряет более выразительный стиль программирования, поскольку устраняет стоимость загрузки чистой, грамотной самодокументации".

Бонус в том, что jsmin также снимает комментарии с CSS - так что вы можете также свободно комментировать комментарии. (Я считаю, что использование классов css имеет решающее значение для написания четкого javascript.)

Это интересная идея использовать PHP для динамического выделения кода и организации файлов javascript. Имейте в виду, что важная оптимизация для веб-приложений заключается в сокращении HTTP-запросов, поэтому часто бывает целесообразно объединять файлы с меньшим размером javascript. (Я обнаружил, что просто конкатенирование сведенных к минимуму js файлов в один файл отлично работает.)