Как документировать простые методы в UML?

Question

Как часть переписывания старого Java-приложения на C #, я пишу Спецификацию разработки программного обеспечения. Проблема, с которой я сталкиваюсь, заключается в том, что метод слишком прост, чтобы возиться с диаграммой последовательности (он не взаимодействует с другими объектами).

В качестве примера у меня есть простой POJO с именем Item, содержащий следующий метод:

public String getCategoryKey() {
    StringBuffer value = new StringBuffer("s-");
    value.append(this.getModelID());
    value.append("-c");
    return value;
}

Цель и алгоритм метода должны быть документированы. Тем не менее, диаграмма последовательности является излишним. Как другие это задокументируют?

(я не беру на себя ответственность за данный метод, это очень старый код, и автор "забыл" поместить свое имя в Javadoc).

Answer 1

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

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

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

То, что у вас есть, есть, на мой взгляд, действие по получению CategoryKey. Сначала вы создаете префикс, затем добавляете имя метода и затем добавляете суффикс. Поэтому я думаю, что диаграмма активности может быть более полезной, чем диаграмма последовательности в вашем случае.

Однако ваш метод довольно прост и может не требовать графической документации UML. Кажется, что важная вещь в вашем методе заключается в том, что это запрос - состояние не изменяется, и он возвращает строку с префиксом, основной частью и суффиксом. Это можно легко описать с помощью постусловия. Для этого вы можете легко использовать описание Javadoc для возвращаемого значения или, если вы хотите быть более точным, вы можете использовать язык OCL (часть стека UML) для описания постусловия.

Answer 2

Планируете ли вы опубликовать документацию по API, а также документацию по UML? Я считаю UML-диаграммы хорошими для описания высокоуровневого дизайна и взаимодействия между несколькими частями системы. Мелкие детали, такие как метод, который вы описываете, лучше всего вписываются в документ API или даже встроенные комментарии.

Поскольку вы портируете на .NET, извлекли ли вы Sandcastle для создания файлов справки из комментариев XML в вашем коде?

Если вы хотите поместить такие мелкие детали в диаграмму UML, я думаю, я бы добавил примечание к классу в диаграмме классов, чтобы кратко описать, как работает этот метод.