How do I document simple techniques in UML?
As part of rewriting an old Java application in C #, I am writing a software specification. The problem I'm having is that the method is too simple to bother with the 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 algorithm of the method should be documented. However, the sequence diagram is overkill. How do others document this?
(I don't take responsibility for this method, it is very old code and the author "forgot" to put his name in the Javadoc).
a source to share
The problem is that sequence diagrams are used to describe message sequences, however, as you point out, the sequence is not interesting enough to be displayed using a sequence diagram.
Another option you have is interaction diagrams, which do not describe sequences but interact objects, however this may not be that important to you - you have few interaction participants and StringBuilder is not an important part of your system I think.
You can also use state diagrams, which are useful for describing the states of cars, however, your object does not change its state with your method.
What you have is, in my opinion, CategoryKey acquisition activity. First, you create a prefix than add a method name and add a suffix. So I think that an activity diagram might be more useful than a sequence diagram in your case.
However, you are simple enough and don't need graphical UML documentation. The important thing about your method seems to be that this is a request - the state is unchanged and it returns a prefix, body and suffix string. This can be easily described using a postcondition. To do this, you can easily use the Javadoc description for the return value, or if you want to be more precise, you can use OCL (part of the UML stack) to describe the postcondition.
a source to share
Are you planning to publish API documentation as well as UML documentation? I find UML diagrams to be good for describing high-level design and interactions between multiple parts of the system. Small details like the method you described are best suited in the API doc or even in the comments.
Since you're porting to .NET, have you checked out Sandcastle for generating help files from XML comments in your code?
If you want to put small details like this in a UML diagram, I think I'll add a note to the class diagram class to briefly describe how this technique works.
a source to share