Как я могу описать внутреннюю работу моего веб-приложения

Question

Я разработал веб-приложение, которое содержит не только некоторые сложные контроллеры, модели и представления, но также некоторые пользовательские библиотеки и базу данных.

Вдобавок к этому есть слой ajax, поэтому: функции javascriptи связанные с ними функции на стороне сервера.

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

Есть ли инструменты для этого?У кого-нибудь была эта проблема раньше?

Answer 1

Хорошим началом было бы начать использовать PHP Documentor (PHPDoc) до того, как ваша кодовая база станет слишком большой. Даже тогда нетрудно вернуться назад и пометить свои классы и т. Д. PHPDoc будет сканировать кодовую базу и создавать документацию, обычно набор документов в Интернете (HTML), но вы также можете создавать PDF и другие. Функции, методы, классы и т. Д. Будут иметь ссылки на связанные элементы вашего кода. Я говорю, прежде чем он станет слишком большим, потому что вы захотите вернуться и добавить теги комментариев для улучшения вывода документов. PHPDocumentor (PHPDoc) можно найти здесь http://www.phpdoc.org/ и информацию и учебные пособия можно найти по всей сети. Если вы зашли так далеко с PHP, то наверняка вы заметили такие комментарии ... (блоки документов)

/**
 *@todo something I need to do
 *@param [type] [$varname] [description]
 *
 */

Эти теги / DocBlocks должны быть проанализированы PHPDoc и очень полезны ... Большинство IDE также очень удобны для использования DocBlocks и иногда улучшают подсказки кода и т. Д., Основываясь на DocBlocks в вашем коде.

Для базы данных ... есть много инструментов и методов, но вот одно из предложений ...

База данных может быть описана инструментами, которые будут строить диаграммы. Например, при использовании MySQL вы можете установить MySQL Workbench, и тогда вы получите инструменты для подключения к базе данных и построения диаграммы, аналогичной рисунку на этой странице ... http://forge.mysql.com/wiki/MySQL_Workbench, плюс множество других инструментов для реверс-инжиниринга и / или проектирования, инструменты для ORM и многое другое. Иногда просто диаграмма и существующая БД может быть очень полезна, особенно когда есть много отношений. MySQL Workbench даст вам возможность отправить диаграмму в PDF или изображение. Все очень полезно.

Это поможет не только будущим разработчикам, но и этим инструментам. Мы все удивлены, осознав, что забываем через несколько недель, месяцев и т. Д., Не глядя на код. Даже насыщенные выходные могут сделать медленный старт снова в понедельник утром.

Для моего последнего предложения ... и я буду прост здесь, но посмотрите на отслеживание ошибок / проблем. Есть много онлайн или вы можете установить свой собственный. Некоторые идут вместе с контролем версий (например, в GitHub, Unfuddle, BitBucket и т. Д.) ... или вы можете установить свой собственный. Я считаю, что Bugzilla довольно легко установить, если вы используете Ubuntu, она находится прямо в хранилище и легко устанавливается.

Answer 2

Это обычно известно как документация "как построено";есть огромное количество информации о паутинах.

Я предпочитаю разделить документацию на несколько разделов;каждый из них так же важен, как и другой, но вам не нужно тратить на них одинаковое количество времени.

Функциональный дизайн

Что должно делать приложение?Какое поведение ожидается?Каковы ключевые поездки пользователей?

Мне нравится использовать сценарии использования или истории пользователей для этого, с различными уровнями детализации.Системная контекстная диаграмма также помогает.Варианты использования могут быть как визуальными, так и текстовыми;часто достаточно пары часов для описания простого приложения

Нефункциональные требования

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

Концептуальный дизайн

Обзор высокого уровнясистема как построенная, определяющая основные компоненты, точки интеграции и зависимости.

Детальное проектирование

Это бит, который наиболее подвержен изменениям, и самая большая проблема, которую нужно поддерживать.Использование PHPDoc - отличный способ поддерживать это в актуальном состоянии.

Приемочные тесты

Даже если вы не участвуете в разработке через тестирование, оставление будущих разработок с методами тестирования работоспособности приложения - отличный способ сохранитьони в здравом уме.В идеале приемочные тесты должны быть автоматизированы / написаны с помощью сценариев (например, с использованием Selenium).

Известные ошибки

Предоставление списка известных ошибок будущим разработчикам мешает им вырвать свои волосы...

Все это может быть большой работой - так много команд используют "формальные" способы общения - вики, фотографии с досок, даже видео с командой, объясняющей дизайн.

Более формально, есть такие стандарты, как UML, которые помогают собирать документацию стандартным способом.

Answer 3

Это, конечно, не полный ответ, который вы ищете, но то, что я всегда нахожу очень полезным, это правильная документация!И да, есть некоторые действительно хорошие инструменты, например PHPDoc .Это частично позволяет вам создавать документацию рабочего процесса, по крайней мере, чтобы объяснить, что именно вы делаете.

Далее вы можете просто объяснить простым языком, как это flows.Если это действительно большое приложение, вы можете даже подумать о создании собственной wiki !