Sequence Diagrams and Parameters

[ttobler]

We use Sequence Diagrams extensively to detail our designs.  We run into several problems with EA and sequence diagrams, as illustrated by the following example:

1. While creating a sequence, I'll discover the need for a method, GetCategoryList( bool cacheList ).

2. I'll use this method in a sequence diagram, and change the argument text so that the message reads as:

 GetCategoryList( cacheList := false )

3. I'll create several sequences, using the above pattern and appropriate value for where cacheList appears.

4. I'll send these diagrams off to be reviewed and implemented.

5. Testing will find some sequence variation that requires an alternative flow to correct a fault with the use case.

6. I'll design an alternate flow, and realize that I need additional parameters, say:

  GetCategoryList( bool cacheEntry, out int cacheEntryCount, out WarningBits warnings )

7. As soon as I update GetCategoryList, EA destroys all those nice arg text values that were used in all those other sequences.  If you go look at those other sequences, the messages now read:

  GetCategoryList( cacheEntry, cacheEntryCount, warnings )

Someone who needs to know whether cacheEntry should be passed in as true or false is sort of screwed -- they either need to try to figure out original intent, or send it back to the developer.


Is there...

A. A way around this problem?

B. A way to figure out which sequence diagrams a particular method is used on.

 - at least worst case, I can open all sequences that use a particular method, get a snapshot, add the parameter, then correct all the diagrams?

C. Any other ways to work around this deficiency?

 - I could attach a note to the method to specify parameters, rather than use the argument text field.  This is ugly, but at least it works.  This looks like, after all the steps above, as:

   GetCategoryList( cacheEntry, cacheEntryCount, warnings ) ---- [NOTE: "Set cacheEntry := false" ]

D. Any plans to correct this problem in future EA versions?  It should not be touching text values I have spent time to manually add, even if it doesn't quite match the message signature.  It would be nice to give me a warning that some don't match, and extra nice if it popped up a dialog that would let me navigate to each diagram that needs to be corrected.

--
 Trent

[jmccabe]

We've also got the issue of parameters in messages in sequence diagrams with EA 6.5. I've had a search through the forum and found this message but note there are no other responses.

We need some way to identify the actual parameters, not just the formal parameters, in sequence diagrams.

Hope for a response.
John

[jmccabe]

We've also got the issue of parameters in messages in sequence diagrams with EA 6.5. I've had a search through the forum and found this message but note there are no other responses.

We need some way to identify the actual parameters, not just the formal parameters, in sequence diagrams.

Hope for a response.
John

[bjones]

Have you tried the putting cacheList := false in the constraint box on the properties page?   or attaching a constraint to the method?

[jmccabe]

Have you tried the putting cacheList := false in the constraint box on the properties page?

Do you mean using the constraint box to identify what the parameter values are?

...or attaching a constraint to the method?

Mm - I saw that was an option, but it seems like a poor workaround, and a lot of effort that I don't think should be necessary.

The thing is, the parameters box is provided on the properties page as an edit box, so it makes sense to be able to change it to show actual (rather than formal) parameters, but if it's going to get overwritten when you change the method signature then it seems like the parameters edit box is unnecessary or certainly should be read-only.

Thanks for the suggestion though.

John

[ttobler]

>> Have you tried the putting cacheList := false in the constraint box on the properties page?   or attaching a constraint to the method? <<

I do not see any constraints on the message.. Am I missing something?  A constraint on the method is certainly not what I'd want to use.  The parameter value is not constant, it depends on the exact message context in which it is used.

Here is an example to illustrate;  Suppose you had a sequence along the lines of:

--ConfigureRefreshMode(allowUpdate:=false)-->
--UpdateDisplay()--------------------------->
--ConfigureRefreshMode(allowUpdate:=true)--->

If I need to include another bool parameter for the ConfigureRefreshMode, and decide to require it (as opposed to include another overload):  ConfigureRefreshMode(allowUpdate:bool,suspendPaint:bool), EA goes and destroys the information concerning the allowUpdate parameter I entered in the sequence above.

If you go and look at the sequence again, you may not be able to easily determine what the parameter value was supposed to be to ensure the detailed sequence works correctly; you have to go and re-analyze the sequence, as opposed to tweaking it to account for the new parameter.

[ttobler]

Never mind, I found the constraints.  I'll think about this one.  It may be what I was looking for.  Thanks, bjones.

[jmccabe]

IMHO It may be a workaround for what you were looking for, but it's certainly not ideal. From all the UML sequence diagrams I've seen in books, tutorials etc, if you're passing parameters in a message, the parametes should be the reference to the real object being passed, not to the name of the formal parameter for the method. Using a constraint is definitely a workaround in my view.

Ideally what I'd like to see happen is for EA, when you change an operation signature, to pop up a list of where that operation is used and let you go and update them or allow you to set a default value. It obviously knows where they are because it replaces the existing parameter information so it shouldn't be a huge amount of effort to implement (I'd have though :-)

John