Документация
После создания программного обеспечения можно написать документацию на готовый продукт с помощью UML. Я считаю, что диаграммы UML очень помогают понять систему в целом. Однако я должен под-
черкнуть, что не верю в возможность создания подробных диаграмм всей системы. Процитирую Уорда Каннингема [14]:
Тщательно отобранные и хорошо написанные заметки могут легко заменить традиционную обширную документацию. Последняя редко проясняет суть вещей, за исключением отдельных аспектов. Выделите эти аспекты ...и забудьте обо всем остальном.
Я полагаю, что подробная документация должна генерироваться на основе программного кода - так, как это делает, например JavaDoc. Для того чтобы подчеркнуть важные концепции, необходимо написать дополнительную документацию. Можно считать ее составной частью первого этапа знакомства с программой, предшествующего детальному изучению кода. Я предпочитаю представлять документацию в виде текста, достаточно краткого, чтобы его можно было прочитать за чашкой кофе, и снабженного диаграммами UML, придающими обсуждению наглядный характер. Очевидно, что составитель документации должен решать, что важно, а что нет, поскольку разработчик вооружен для этого значительно лучше, чем читатель.
Диаграмма пакетов представляет хорошую логическую маршрутную карту системы. Эта диаграмма помогает понять логические блоки системы, а также обнаружить их взаимозависимости и держать их под контролем. Диаграмма развертывания (см. главу 8), которая показывает физическую картину системы на верхнем уровне, также может оказаться полезной на этой стадии.
Для каждого пакета я предпочитаю строить диаграмму классов. При этом я не указываю каждую операцию в том или ином классе, а показываю только важные свойства, которые помогают мне понять общую картину. Такая диаграмма классов служит своего рода оглавлением в виде графической таблицы.
Диаграмму классов следует сопроводить несколькими диаграммами взаимодействий системы, которые показывают наиболее важные из них. Повторюсь: правильный отбор очень важен; помните, что в документации такого типа полнота - враг понятности.
Если некоторый класс в течение своего жизненного цикла имеет сложное поведение, то для его описания я строю диаграмму конечного автомата (глава 10). Но делаю это только в случае достаточно сложного поведения, что, на мой взгляд, бывает очень редко.
В книге также часто встречаются фрагменты программного кода, важные для понимания системы и профессионально написанные. Кроме того, я использую диаграмму деятельности (глава 11), но только если она обеспечивает мне лучшее понимание, чем сам код.
Сталкиваясь с повторяющимися понятиями, я описываю их при помощи шаблонов (стр. 54).
В документации важно отразить неиспользованные варианты дизайна и пояснить, почему они были отброшены. Об этом часто забывают, но
такая информация может оказаться самой важной для ваших пользователей.