UML tool for team development

[Gerardo Tasistro]

Originally posted by Ilja Preuss:


It doesn't show the need for documentation, but need for critical reflection on what we are doing. It shows that practices that might have made sense yesterday could be just silly today. That we tend to do things just because we are used to them, because "it is the right thing to do", not because they still provide value.

Ha! But there lays the problem you see. You, as a reader of my post, are in a priviledged position. You know the whole story. You know that the original reason was the water. But for all the final monkeys the reason is that you get beaten. They never got wet from reaching for the bannana.

This applies to program development too. As a new member of the team you might want to go somewhere with an undocumented project only to find yourself "beaten" out of the idea for no apparent reason. Or worse yet actually take the project in another "more reasonable direction" only to get everybody "wet".

Case study of this could be an experience I had with a VPOS (virtual point of sale) terminal about 3 years ago (when did Nimda hit?). Back then our bank ran the VPOS on NT and all was well. We interfaced our system with theirs according to the manual and all was well. Then Nimda hit. Our BSD servers didn't even notice it, but the VPOS started to go wild. Returning op codes that were not even in the bank's documentation. We patched the system for this and other worms that were to come later on.

We had to do "agile" development. Heck this patch needed to be on right then and there. We analized it moved the code around and patched it.

After we got done we had two options. Document the changes in a diagram that already exists or throw the whiteboard diagram away. After all "agile development" was a success. We patched within an hour of the problem being detected. Hurray!

Lets see. Behind door A:

Without the documentation written down and this fix added into the the diagram future developers don't know why this apparent loop, buckle and switch is there. Remember the bank's documentation mentions nothing of these cases. We are beating the monkey for no apparent reason.

Future development will incorporate this "feature" and will keep beating more monkeys as they come into the team. Or future development can say, "Hey what is this for? Take it out." In other words. Forget the beating sneak up to the bannana to get it. Only to get everyone wet and above that earn yourself a beating.

Or behind door B:

We have a diagram of the flow of the critical processes and we add the modification showing why this is there and what precautions need to be considered. That way if future implementations use another system or bank (the sprinkler is removed) that loop doesn't need to be included (we can go for the bannana). We now know that the real reason behind the beating is the sprinkler and not the "bannana's shadow". You can change monkeys around all you want. The five in the room will know not to reach for the bananna while the sprinkler is there and will know to reach for it once the sprinkler is gone.

I think this is a good example because in involves a lot of money. The stakes for good documentation and integration are high. It cost the bank's clients money. Had we been a bigger operation we might have been in a position to sue them. And lawyers charge more than programmers.

Oh, btw. We took door A and learned the lesson. Fortunetly we changed bank shortly afterwards. So it wasn't a tough lesson to learn, but it was close enough to get you thinking you could have done better.

[Gerardo Tasistro]

Originally posted by Ilja Preuss:


That's an interesting analogy. When a doctor needs to operate on someone, he typically doesn't rely on x-ray from years ago, does he. You also don't have x-rays made of yourself every week, just in case, do you?

Oh I just love how you move from literal to figurative as it benfits you. Setting aside the fact that doctors (of the medical type << hey got to be literal with you less you happen to catch me there) don't generally program. Would you feel better if I had said CAT scan? Or maybe I should have said blueprint. But wait. With all these new PC CADs who has blueprints anymore.



I swear Ilja sometimes you just make my day with your comments.

[Mark Spritzler]

I think Gerardo example of the monkeys is a good example. I see it too much, we use this product because we have always used this product, so it must be right.

But, it might not fit completely against Agile, it might be that we write down not to get the bananas, and never update it later, and even when no more water comes down, they still won't go for the bananas. But I think it is a good example of what happens in IT, that Agile itself won't fix either, and can add to that problem.

I also want to point out that I am not against Agile Methodology, the methodology as written can work extremely well in some environments, just not all. And I think many people interpret it differently. And I still see , in the companies that I have seen, implement it just to put a name to their chaos.

We use Agile here, and we are also including Functional Specs, Technical Specs and Detail Design documents, so we are getting to document things down, and I think it works better.

Mark

[Mark Spritzler]

Here is a different example of Agile. Since you want to work on getting things done at a good pace, you don't spend the up front time to make process/standards/architectural decisions until needed. So it allows for some really bad code to get into your codebase quickly, and found out later when it will take a long time to correct what was done before.

We are in that exact boat right now, even on things as simple as using an int to store the Primary Key value. But in the call to the Database it needs an object and does logic based on whether the PK is null or not, so the mapping is a pain because you now have to check to see if the int is 0 then set the other object to null, and the smae the other way around. This is because they didn't think ahead and plan and set standards up front.

This is a small example of many issues we have here because of things not done up front that would have saved so much time and money, but it appears that there is way to much risk assumed, and the probability of being bitten is too high. And by the time you find out, it is usually too late. I can guarantee you that the issues here costs at least 2 Million more dollars to the project, that spending 100K up front would have saved.

Mark

[Gerardo Tasistro]

Originally posted by Mark Spritzler:
And I still see , in the companies that I have seen, implement it just to put a name to their chaos.

So so so true.

[Ilja Preuss]

Originally posted by Mark Spritzler:
Here is a different example of Agile. Since you want to work on getting things done at a good pace, you don't spend the up front time to make process/standards/architectural decisions until needed. So it allows for some really bad code to get into your codebase quickly, and found out later when it will take a long time to correct what was done before.

Well, as you are probably aware of, Agile Software Development is not at all about getting a "good pace" at the beginning at the expense of a slow down later. Quite to the contrary, it's about keeping a sustainable pace.

So, no Agile process I know allows for "some really bad code to get into your codebase quickly" - that sounds more like "code and fix" to me...

We are in that exact boat right now, even on things as simple as using an int to store the Primary Key value. But in the call to the Database it needs an object and does logic based on whether the PK is null or not, so the mapping is a pain because you now have to check to see if the int is 0 then set the other object to null, and the smae the other way around. This is because they didn't think ahead and plan and set standards up front.

I'm not sure I understand this example. What did you need the primary key value for before you had a database?

And what makes your team think that it is doing *Agile* software development?

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Setting aside the fact that doctors (of the medical type << hey got to be literal with you less you happen to catch me there) don't generally program.

Well, you brought up the analogy, not me. Don't blame me for accepting it.

Would you feel better if I had said CAT scan?

Actually, I feel quite well, thank you.

Or maybe I should have said blueprint.

Maybe. That depends, of course, on what point you wanted to make.

As a learned precision mechanic, I actually have some thoughts on why blueprints are used in the hardware world, on how those reasons map to software development.

But wait. With all these new PC CADs who has blueprints anymore.

Don't forget all the new materials for low cost prototyping, and software simulations, which allow a much tighter feedback loop between theoretical design and actually seeing the result in action.

I swear Ilja sometimes you just make my day with your comments.

Well, than I guess this has at least one purpose.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Ha! But there lays the problem you see. You, as a reader of my post, are in a priviledged position. You know the whole story. You know that the original reason was the water. But for all the final monkeys the reason is that you get beaten. They never got wet from reaching for the bannana.

In my opinion, the problem would better be solved by a new monkey asking the old timers "Why do you beat me? You don't know? Why haven't you ever asked? So, now that we are in this situation, how we can make it an acceptable risk to find out what happens if we touch the banana?"

And I'm actually not at all against putting a "beware of the water" sign next to the banana (or, preferably, directly onto the banana).

Having a cabinet of documentation such as "delouse each other because..." and "don't touch banana, or you will get wet" simply sounds like an inferior solution to me...

Without the documentation written down and this fix added into the the diagram future developers don't know why this apparent loop, buckle and switch is there. Remember the bank's documentation mentions nothing of these cases.

An XP team, for example, would write an executable test for this feature and name it accordingly. It might even add some prose.

Or future development can say, "Hey what is this for? Take it out." In other words. Forget the beating sneak up to the bannana to get it. Only to get everyone wet and above that earn yourself a beating.

In an Agile team, that would make at least one test break. The team could then analyze whether the test still tested for something sensible, or whether it could be deleted, too.

As I said, Agility is not at all about not caring about the future.

Oh, btw. We took door A and learned the lesson. Fortunetly we changed bank shortly afterwards. So it wasn't a tough lesson to learn, but it was close enough to get you thinking you could have done better.

Well, yes, you could have done better. And I'm glad you put "agile" into quotes, because it wasn't *Agile* what you did. Saying so would just have been putting the Agile label on your "chaos".

[Ilja Preuss]

Going with the testing idea, the optimal Agile solution would have been:

a button at the wall with a banana and a water symbol on it. When you press it, glas walls separate the monkeys from the banana, and a monkey robot appears who touches the banana. That way, the monkeys could see whenever they wanted, without any risk, what happens when you touch the banana.

[Gerardo Tasistro]

Originally posted by Ilja Preuss:


In an Agile team, that would make at least one test break. The team could then analyze whether the test still tested for something sensible, or whether it could be deleted, too.

And how exactly would you test that? Put another Windows NT worm on the wild? You did pay attention to the cause of the bug, right?

That aside what is your position on documentation. Is it not needed at all? Is it neede to some degree (and what degree would that be for you)? Is it needed extensively?

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
And how exactly would you test that?

What exactly did you do to fix the problem? How did you know that it worked?

Put another Windows NT worm on the wild?

Well, that would be quite low on my list... :roll:

You did pay attention to the cause of the bug, right?

Yes. I cannot say that I have a very clear picture of what you did, though.

Anyway, perhaps this really was one of the very very rare cases where a software fix cannot be automatically tested for. In which case you are right: you should have found some other way to document its existance, perhaps even the diagram.

Which doesn't change my point: you weren't Agile, you were - with all due respect - sloppy.

That aside what is your position on documentation. Is it not needed at all? Is it neede to some degree (and what degree would that be for you)? Is it needed extensively?

We try to write clean, well factored, "self explanatory" code.
We try to write expressive, extensive unit tests for the code.
We currently work on getting FitNesse running in our environment, to write "executable specifications" for new features.
We have a team wiki, where we write down important information that we fear might otherwise get lost.
We write release notes, and have a technical writer on the team who updates the online help and user manual accordingly.
We have a couple of charts hanging in the team room, for example showing the history of our CVS branches, including merges and distributions; and a list of "Meta Stories", such as "canceled is to be written with one 'l'".
We try to write expressive commit comments.
We just added to our build environment a task that creates an XML document showing all the dependencies between distribution jars, CVS modules and thirdparty jars.

All of this helps us writing software of higher quality more effectively (well, perhaps not the last point - that's still experimental).

We don't typically archive UML diagrams. We tried. It didn't help us.
[ February 03, 2006: Message edited by: Ilja Preuss ]

[Gerardo Tasistro]

Originally posted by Ilja Preuss:


We don't typically archive UML diagrams. We tried. It didn't help us.

[ February 03, 2006: Message edited by: Ilja Preuss ]

Why was that?

[Mark Spritzler]

We try to write clean, well factored, "self explanatory" code.
We try to write expressive, extensive unit tests for the code.

This is where the problem lies, not in the methodology, but in the practicality and reality of the real world.

In general, we try to do these things, no matter what methodology we follow. I'd say there are more who try to do this, but because of ego, talent, and other things, it isn't defined. Meaning, everyone has their own opinions of what that means, and you can have some really bad code from an old C programmer who still wants to write all their code low level, rather than use what is provided, and thinks that that is clean, well factored, expressive code, but it isn't.

With Agile, there just isn't enough checks and balances to stop that from happening, whereas a more formal process does.

Mark

[Ilja Preuss]

Originally posted by Mark Spritzler:

With Agile, there just isn't enough checks and balances to stop that from happening, whereas a more formal process does.

With Promiscuous Pair Programming and Collective Code Ownership, the whole team will know about the coding style in a matter of days. If they think it's a problem (and I probably would), the team has to address it in some way.

XP, for example, advices to have the team develop a team Coding Standard. And perhaps the C oldtimer just needs some OO training...

I seriously don't think that a more formal process has more checks and balances - only more formal ones.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:


Why was that?

Noone ever looked at it.

I have a theory on why this happened - a combination of several points:

- the UML diagram was good for the task it was generated for, but for subsequent tasks, it contained the wrong details and omissions.

- even the original value of the diagram was more in the doing than in the result. Even directly after having drawn the diagram, we didn't look at it very much - the important information mostly was already in our heads.

- because of the above two points, noone was motivated to update it, so after a while it became out of date.

That's not to say that I will never again touch a UML tool. But knowing the existent design of the system isn't a pressing problem for us, so we focus our efforts on other things (such as learning FitNesse and being able to even more mercilessly *improve* the design without breaking things).

[Gerardo Tasistro]

What tool did you use for UML? Could you add comments and documentation sniplets to it?

[Don Morgan]

I seriously don't think that a more formal process has more checks and balances - only more formal ones.

This is one of the better single sentence comparisons I have heard between Agile processes and more formal ones and I think it really rings true. Let me edit slightly:

A more formal process does not have more checks and balances than an agile one - only more formal ones.

[Mark Spritzler]

But Agile is not always pair programming, and in our case it is not it is Scrum, Sprints, Stories and tasks, so there is absolutely no checks or balances. With a formal process there are code reviews, checkin can only occur with both the reviewer and coder agreeing. The coding standards are written out. The process has enough up front diagramming and document creation that there are review processes there to catch problems before they occur, which saves lot and lots of money.

Mark

[Gerardo Tasistro]

Originally posted by Don Morgan:


A more formal process does not have more checks and balances than an agile one - only more formal ones.

I think agile development can be as formal as any other development model. Actually agile by its nature needs to be formal to prevent from falling into caos.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
What tool did you use for UML?

I'm not sure. I remember that we started by trying several. But this was around two years ago or something...

Could you add comments and documentation sniplets to it?

Yes, I'm sure we could.

In my career, I've used a number of UML tools - Together, Rational Rose, UMLet, Visual Thought, Poseidon etc. We even tried Diag, for a very short time. Small Worlds was an interesting program, too, but couldn't handle the size of our code base.

What I found surprising is that the high end tools often even don't allow you to draw an association class, or had trouble fitting the text into the boxes when printing the diagrams...

Anyway, it *could* be that I just haven't yet found the right tool, but I'm more inclined to believe that our needs really are different.

What I find much more helpful, for example, is a tool that helps me analyze the structure of the design "just in time" - such as the heirarchy view and the call hierarchy of Eclipse.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:

I think agile development can be as formal as any other development model. Actually agile by its nature needs to be formal to prevent from falling into caos.

I have the feeling you are confusing formality and discipline.

[Gerardo Tasistro]

Originally posted by Ilja Preuss:


I have the feeling you are confusing formality and discipline.

Why?

[Mark Spritzler]

You know eventually, we have to go our seperate ways, or this might end up being the next Word Association thread.

Mark

[Ilja Preuss]

This is also getting very off topic.

I started a new thread at https://coderanch.com/t/130614/Agile/Agility-formality-vs-discipline - should someone still be interested...

[Shalin Siriwardhana]

Creately UML tool is one of the best I know as it is up to date. The latest UML version consist of 14 major diagram types. The latest version is 2.5.1. And there are many examples and templates in the diagram community as well.

Disclaimer: I use creately for projects