1

I am using UML to document parts of an older c++ program. It's only a portion of the code, but documenting it has made me insane since even this process is quite large. So far I have used class diagrams for the relevant code and some activity and sequence where necessary.

My question is I feel what I have done so far is good for the overall documentation but I want to get down to the dirty details of a few methods and one of them is 202 lines long, what should I use for this? An activity diagram or sequence?

I am using Visio for the UML documentation.

Thanks.

Dixon Steel
  • 1,021
  • 4
  • 12
  • 27

3 Answers3

0

A rule of thumb might be that if it seems like there are multiple agents handing off flow between each other, use sequence; otherwise, activity. In a single function, activity is probably best - but not necessarily.

Try to imagine what it's going to end up looking like, put yourself in your ignorant reader's shoes, and think about which will tell the story better.

Is splitting up the function an option?

Ed Staub
  • 15,480
  • 3
  • 61
  • 91
  • Yes, I could break up the function, it's not desirable but I could. The code is rather fragile and hard to read, but I have to eventually pull it apart anyway. – Dixon Steel Jul 11 '11 at 12:31
  • Consider using tooling to help. See [various tools](http://stackoverflow.com/questions/1388469/is-there-a-working-c-refactoring-tool) and [Eclipse](http://stackoverflow.com/questions/130913/what-is-the-state-of-c-refactor-support-in-eclipse), both posts a little old. I'm a Java guy for the last 5 years, and one of the real delights has been the availability of excellent refactoring support in the IDEs. – Ed Staub Jul 11 '11 at 12:46
0

The question is: Do you want to describe the process or the interactions between objects that those few methods are executing? The process can be broken down into activities which are performed, their composition and data flow. Interactions are comprised of messages sent between objects.

Gabriel Ščerbák
  • 18,240
  • 8
  • 37
  • 52
0

Well,

Short answer is:

If you want to document an algorithm (that is used by one of your system object^s method): Use Activity diagrams.

Long Answer:

For my experience UML documentations are the worst ones.

People generally use Uml Tools which automaticly reverse engineer code to Uml (generally class diagrams, and sometimes sequence diagrams) and diagrams that are automatically generated are generally has many details and sometimes nonsense.

As an advice "Comments your code properly" and use tools like Doxygen. They are better for Code Documentation.

But you can use UML for Software Architect Document.[SAD]. Craig Larman has nice section and example of it at his books about Documenting Architecture

Motivation: Why Create a SAD? When someone joins the development team, it's useful if the project coach can say, "Welcome to the NextGen project! Please go to the project website and read the ten page SAD in order to get an introduction to the big ideas." And later, during a subsequent release, when new people work on the system, a SAD can be a learning aid to speed their comprehension.

Therefore, it should be written with this audience and goal in mind: What do I need to say (and draw in the UML) that will quickly help someone understand the major ideas in this system? [ Applying UML and Patterns Third Edition By Craig Larman ] [Chapter 39. Documenting Architecture: UML & the N+1 View Model]

Novalis
  • 2,265
  • 6
  • 39
  • 63
  • I thought about Doxygen but as you said it the automatic generation sometimes looks like nonsense, and it has when tried on other parts of the code. I may go with the advice of breaking this up and try a sequence diagram. – Dixon Steel Jul 11 '11 at 12:37
  • @ Dixon Steel If you want to give details of algorithm, activity may be better choice.Sequence diagrams are more suitable object interactions – Novalis Jul 11 '11 at 14:16