UML and Documenting Simple Diagrams

Question

As part of a rewrite of an old Java application into C#, I'm writing an actual Software Design Specification. A problem I run into is when a method is too simple to bother with a Sequence Diagram (it doesn't interact with other objects).

As an example, I have a simple POJO called Item, containing the following method:

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

The purpose and the algorithm for the method needs to be documented. However, a sequence diagram is overkill. How would others document it?

(I take no credit/blame for the given method, it's very old code and the author "forgot" to put their name in the Javadoc).

Answer 1

The problem you have is that sequence diagrams are used for describing sequences of messages, however as you point out, the sequence is not interesting enough to be depicted using sequence diagram.

Another option you have are interaction diagrams, which do not describe sequences, but interacting objects, however, this might be not as important for you - you have not many participants in the interaction and the StringBuilder is not important part of you system I guess.

You might also use the state diagrams, which are useful for describing state machines, however your object does not change its state through your method.

What you have there is in my opinion an activity of obtaining the CategoryKey. Firstly you create a prefix, than add the method name and than add the suffix. So I think activity diagram might be more useful then sequence diagram in your case.

However, you method is quite simple and might not need any graphical UML documentation. The important thing about your method seems to be that it is a query - no state is changed, and it returns a string with prefix, main part and suffix. This could be easily described using postcondition. For that you can easily use the Javadoc description for the return value or if you want to be more precise, you can use the OCL language (part of UML stack) to describe the postcondition.

Answer 2

Are you planning to publish API documentation as well as the UML documentation? I find the UML diagrams good for describing high-level design and interaction between several parts of the system. Small details like the method you describe seem to fit better in an API document or even in-line comments.

Since you are porting to .NET, have you checked out Sandcastle for generating help files from the XML comments in your code?

If you do want to put small details like this in a UML diagram, I think I would add a note to the class in a class diagram to briefly describe how this method works.