"How can I do my design when I haven't written the (expletive deleted) code yet?" a former colleague yelled quite irately as I passed by a manager's office. Now I know Joe. Yes, sometimes he would start out coding and end up with some useless methods and classes. But Joe always had an idea of his code's basic structure. What Joe meant to say was that he could not write the detailed documentation of his design because he hadn't worked out all the details yet.
Unfortunately, many developers look at modeling the way Joe looked at design -- as a documentation step to be completed rather than something that helps the goal of producing properly executing code quickly and efficiently.
Modeling helps developers visualize the structure, interactions, and behavior of the system they are building (NB: I used the plural because developers seldom work alone. One must be able to communicate one's ideas; more on that in another article).
In fact, in a 2008 survey by Scott Ambler found that the vast majority of developers used high level diagrams. From my own practice, I'm assuming that the majority use class diagrams to define structure. I'll bet that a fair number of developers use some variation of sequence diagrams when discussing interactions as well. Here is my point: If you are already using these two common diagrams, why not capture the artifacts in a tool rather than on a white board? Doing so makes the artifacts reusable and captures the design rationale for the rest of the team (including reviewers and maintainers).
Bottom line: if Joe had captured his thoughts in a model, he wouldn't have had the scream match with his boss. He might even still be working there.
Tuesday, April 17, 2012
Thursday, April 12, 2012
Refining Use Cases with Activity Diagrams
In a previous post, I discussed text based use case descriptions. This post discusses a graphical method: activity diagrams.
Before discussing the advantages of refining use cases with activity diagrams, let's define activity diagrams. One of my colleagues describes them as "flow charts on steroids." Activity diagrams show the possible sequences of activities and the flow of data between activities in a single view.
The rectangles with rounded corners represent activities. In the software world, an activity would be implemented as a functions or method. On this diagram, the dashed red lines represent the order that the actions occur.
Unlike text, graphical activity diagrams are not open to interpretation. Even people not trained in UML's or SysML's subtleties understand an activity diagrams flowchart-like structure. Complicated concepts, including exception condition handling, become clear when viewed on a single page.
Note that you may use nested activity diagrams (not what they are called, we'll get to the proper name later) to describe complex actions.
In summary, the advantages of using activity diagrams to refine use cases include:
Before discussing the advantages of refining use cases with activity diagrams, let's define activity diagrams. One of my colleagues describes them as "flow charts on steroids." Activity diagrams show the possible sequences of activities and the flow of data between activities in a single view.
Unlike text, graphical activity diagrams are not open to interpretation. Even people not trained in UML's or SysML's subtleties understand an activity diagrams flowchart-like structure. Complicated concepts, including exception condition handling, become clear when viewed on a single page.
Note that you may use nested activity diagrams (not what they are called, we'll get to the proper name later) to describe complex actions.
In summary, the advantages of using activity diagrams to refine use cases include:
- Graphical representation is not open to interpretation the way text is
- Shows multiple paths (including exception conditions) in one view
- Complex actions may be further refined with other activity diagrams
Monday, July 11, 2011
UML Hell Doesn't Exist.
Recently, customer gave me a paper that basically said that modeling is a mistake and that it takes too much time for the benefits. The author states that UML is strictly an academic concept that has no place in the commercial world. He states several problems including the model not representing the code and modeling slowing down the development process.
Obviously, I disagree. In fact, I disagree so strongly, that I'm not going to give the link to the paper. I will, however, share what I told my customer.
True, modeling just for the sake of modeling provides little value. It is entirely possible to model to such fine detail that the model misses its purpose. In the Systems Engineering realm, the purpose of the model is to specify what the system must do, not how the system does it. Any modeling that describes how is a waste. The advantages of Systems modeling are fewer missed exception conditions, fewer duplications of effort by multiple subsystems, better definition of the interfaces, and better understanding of the subsystems' responsibilities.
In the software realm, models show the desing -- how the system implements the requirements. I am assuming, of course, that you see value in designing your system before you start coding. Typically, designs include the software structure, class/file interactions, and function/method behavior necessary to build the software. A UML model, therefore, includes the exact same information you are required to deliver in an SDD. In fact, you should generate your SDD directly from your model. The advantages of software modeling include better understanding of (by all stakeholders) of the system's functionality, better design reviews, better structural design, less time to develop code, and increased reusability.
If you use the right tools, modeling decreases development time. There are several tools on the market today that generate code directly from the model. Now, the "fitness" of the code varies with the tool. Some require you to make all changes directly in the tool; the code is really not user editable. Others, produce only "code-frames," the header files and the method signatures. I don't recommend using products like these.
Instead, find a product that generates full, production quality code directly from the model. The code should be readable and editable with your favorite editor. Similarly, you should be able to use your tool to visualize existing code. (email me and I'll give you the names of the tool I like)
The proof of the pudding is in the tasting, so rather than get in a war of words with the author of the other paper, I'll point to Dr. Jerry Krasner's paper What to do When the Horse You're Riding Drops Dead. Dr. Krasner's research showed that organizations that model and generate the code from the model finish their projects on time and hand code fewer lines of code to accomplish the same task.
I also add my own experiences. I used to run a software development group that produced the machine control software for high speed mail sorting equipment. My development team had 5-7 people. We developed routinely developed more code, in less time, with fewer erros than groups of 15-20. The other teams had to stop developmetn for 2 weeks a quarter to update documents. I generated our documents while the team was at lunch.
Bottom line: UML helps real projects develop software faster and with fewer errors.
Obviously, I disagree. In fact, I disagree so strongly, that I'm not going to give the link to the paper. I will, however, share what I told my customer.
True, modeling just for the sake of modeling provides little value. It is entirely possible to model to such fine detail that the model misses its purpose. In the Systems Engineering realm, the purpose of the model is to specify what the system must do, not how the system does it. Any modeling that describes how is a waste. The advantages of Systems modeling are fewer missed exception conditions, fewer duplications of effort by multiple subsystems, better definition of the interfaces, and better understanding of the subsystems' responsibilities.
In the software realm, models show the desing -- how the system implements the requirements. I am assuming, of course, that you see value in designing your system before you start coding. Typically, designs include the software structure, class/file interactions, and function/method behavior necessary to build the software. A UML model, therefore, includes the exact same information you are required to deliver in an SDD. In fact, you should generate your SDD directly from your model. The advantages of software modeling include better understanding of (by all stakeholders) of the system's functionality, better design reviews, better structural design, less time to develop code, and increased reusability.
If you use the right tools, modeling decreases development time. There are several tools on the market today that generate code directly from the model. Now, the "fitness" of the code varies with the tool. Some require you to make all changes directly in the tool; the code is really not user editable. Others, produce only "code-frames," the header files and the method signatures. I don't recommend using products like these.
Instead, find a product that generates full, production quality code directly from the model. The code should be readable and editable with your favorite editor. Similarly, you should be able to use your tool to visualize existing code. (email me and I'll give you the names of the tool I like)
The proof of the pudding is in the tasting, so rather than get in a war of words with the author of the other paper, I'll point to Dr. Jerry Krasner's paper What to do When the Horse You're Riding Drops Dead. Dr. Krasner's research showed that organizations that model and generate the code from the model finish their projects on time and hand code fewer lines of code to accomplish the same task.
I also add my own experiences. I used to run a software development group that produced the machine control software for high speed mail sorting equipment. My development team had 5-7 people. We developed routinely developed more code, in less time, with fewer erros than groups of 15-20. The other teams had to stop developmetn for 2 weeks a quarter to update documents. I generated our documents while the team was at lunch.
Bottom line: UML helps real projects develop software faster and with fewer errors.
Sunday, May 16, 2010
Text-Based Use Case Template
I promised a text based use case template some time ago, and now I'm posting it. This template is loosely based on the work by Alistair Couckburn.
Use Case Description
The first thing you will want to do is make it your own by customizing the template to meet your organization. For example, I found that the version number was not valuable because we used a configuration management system to maintain the documents. Therefore, the most recent copy was at the tip of the archive -- a much simpler solution.
Next, you need to create some "Use Case Standards." In my organizations, we number the main flow steps. When an exception occurs, we put, where x is the number of the exception, at the end of the main flow step. Each item in the Exception Scenario part begins with EXCEPTION x. We keep the exception conditions and main flows together by following this practice.
Next time, using Activity Diagrams to Describe Use Cases
Use Case: | |
Version: | 1.0 |
Description: | |
Scope: | |
Level: | |
Primary Actor(s): | |
Trigger: |
Assumptions:
Preconditions: | |
Success End Condition: | |
Failed End Condition: | |
Assumptions: |
Main Scenario:
Exception Scenarios:
Extensions:
Other Information:
The first thing you will want to do is make it your own by customizing the template to meet your organization. For example, I found that the version number was not valuable because we used a configuration management system to maintain the documents. Therefore, the most recent copy was at the tip of the archive -- a much simpler solution.
Next, you need to create some "Use Case Standards." In my organizations, we number the main flow steps. When an exception occurs, we put
Next time, using Activity Diagrams to Describe Use Cases
Tuesday, December 22, 2009
Use Cases - Overview
Use Cases cause a lot of confusion for many people new to UML and SysML. The OMG UML Infrastructure specification calls Use Cases "a means for specifying required usages of a system. Typically, they are used to capture the requirements of a system, that is, what a system is supposed to do." (OMG Unified Modeling Language (OMG UML) Superstructure, V2.1.2, p. 585). This definition seems a bit academic, so let me try to bring some practical world experience.
Let's be clear: Use Cases ARE requirements. They provide much more than simple shall statements, however. From a Systems Engineering perspective, think of about the problem space this way: a Request for Proposal or Statement of Work provides the requirements for any competitor's solution, but your Use Cases explain your organization's specific solution. They list the capabilities of the system. You will use the descriptions to allocate functionality to different parts of the system. Taken together, the Use Cases described your proposal. Each of the functional shall statement requirements should trace from a Use Case.
Since Use Cases detail the system requirements, they tell what the system will do, not how the system will do it. Use Cases do not show functional decomposition, nor do they specify how to write the code.
Another confusing aspect of use cases are the relationships « extends » and « includes » . I am not going to spend much time describing these here because it is an academic argument. Whether you show a capability as « extends » or « includes » is almost irrelevant. Either way, you will need to detail the additional Use Case. Therefore, I only use « includes » ; and then I only use it when multiple Use Cases require the exact same capability.
A Use Case's meat exists in its description. The description shows, step by step, what the system does to implement a capability. It shows the response to external stimuli (Actors). As important, a Use Case description shows the exception conditions when the normal flow of events does not happen. These discussions of exception handling show the real power of Use Cases. They force the engineers, both Systems and Software, to think about the exception conditions up front.
In the next two sections, we will discuss different methods for detailing Use Cases. The first method uses text. The second uses and Activity Diagram.
Let's be clear: Use Cases ARE requirements. They provide much more than simple shall statements, however. From a Systems Engineering perspective, think of about the problem space this way: a Request for Proposal or Statement of Work provides the requirements for any competitor's solution, but your Use Cases explain your organization's specific solution. They list the capabilities of the system. You will use the descriptions to allocate functionality to different parts of the system. Taken together, the Use Cases described your proposal. Each of the functional shall statement requirements should trace from a Use Case.
Since Use Cases detail the system requirements, they tell what the system will do, not how the system will do it. Use Cases do not show functional decomposition, nor do they specify how to write the code.
Another confusing aspect of use cases are the relationships « extends » and « includes » . I am not going to spend much time describing these here because it is an academic argument. Whether you show a capability as « extends » or « includes » is almost irrelevant. Either way, you will need to detail the additional Use Case. Therefore, I only use « includes » ; and then I only use it when multiple Use Cases require the exact same capability.
A Use Case's meat exists in its description. The description shows, step by step, what the system does to implement a capability. It shows the response to external stimuli (Actors). As important, a Use Case description shows the exception conditions when the normal flow of events does not happen. These discussions of exception handling show the real power of Use Cases. They force the engineers, both Systems and Software, to think about the exception conditions up front.
In the next two sections, we will discuss different methods for detailing Use Cases. The first method uses text. The second uses and Activity Diagram.
Saturday, December 19, 2009
Why Model
The model specifies what a system does and how it does it. Logically, therefore, one starts modeling by deciding what the system is going to do. In traditional, document-driven development, one starts with a Request for Proposal (RFP) or Statement of Work (SOW), writes a proposal or System Specification Design Document (SSDD), writes the System Requirements Specification (SRS), and finally writes a System Design Document (SDD). This methodology has worked for the last 50 years and I'm not suggesting that modeling should replace it. For one reason, many contracts require text deliverables. Rather, modeling augments this process.
Text is a very poor way for engineers to communicate. For the most part, engineers are visual people. If I were to ask you to go to whiteboard and describe the system you are currently working on, odds are pretty good that you will not write a bunch of paragraphs. You will draw some circles and boxes and maybe some arrows to describe the flow. In fact, the main reason we text documents to communicate is because computers come with keyboards.
Another problem with text is that words have different meanings in different industries and different parts of the country. Take the word "fixing." It might mean repairing. Or, especially around the holidays, it might refer to side dishes. Here in Fort Worth, Texas, it means you are getting ready to do something.
Not only do words have shadow meanings, but not all of our coworkers are native English speakers. We may work with colleagues overseas. More likely, at least one team member grew up speaking a language other than English.
Another problem with text-based requirements is how we were all taught to write. Each of us had a high school English teacher, for me it was Miss Feage, who said "vary you sentence structure" and "use descriptive verb." While this advice applies when writing the Great American Novel, it does not apply when writing the Great American Requirements Specification. For a requirements specification, we expect "subject shall requirement." Unfortunately, I have yet to see a customer document written in this format.
Building specifications in UML and SysML avoid all of these problems. UML and SysML are graphical languages. Engineers and Computer Scientists relate better to diagrams than to text. Furthermore, the graphics help engineers see the part of the system under consideration in a single view. This view helps them identify missing exception conditions and inconsistencies.
UML and SysML have very distinct syntax. This syntax is designed to specify structure, interaction, and behavior in a distinct manner that, if used properly, is not open to misinterpretation. And when it comes time to generate the deliverable documents, the better modeling tools support generating the documents directly from the model.
Bottom line: modeling is more natural than text, will help you avoid and identify errors earlier, and still lets you follow your existing processes.
Text is a very poor way for engineers to communicate. For the most part, engineers are visual people. If I were to ask you to go to whiteboard and describe the system you are currently working on, odds are pretty good that you will not write a bunch of paragraphs. You will draw some circles and boxes and maybe some arrows to describe the flow. In fact, the main reason we text documents to communicate is because computers come with keyboards.
Another problem with text is that words have different meanings in different industries and different parts of the country. Take the word "fixing." It might mean repairing. Or, especially around the holidays, it might refer to side dishes. Here in Fort Worth, Texas, it means you are getting ready to do something.
Not only do words have shadow meanings, but not all of our coworkers are native English speakers. We may work with colleagues overseas. More likely, at least one team member grew up speaking a language other than English.
Another problem with text-based requirements is how we were all taught to write. Each of us had a high school English teacher, for me it was Miss Feage, who said "vary you sentence structure" and "use descriptive verb." While this advice applies when writing the Great American Novel, it does not apply when writing the Great American Requirements Specification. For a requirements specification, we expect "subject shall requirement." Unfortunately, I have yet to see a customer document written in this format.
Building specifications in UML and SysML avoid all of these problems. UML and SysML are graphical languages. Engineers and Computer Scientists relate better to diagrams than to text. Furthermore, the graphics help engineers see the part of the system under consideration in a single view. This view helps them identify missing exception conditions and inconsistencies.
UML and SysML have very distinct syntax. This syntax is designed to specify structure, interaction, and behavior in a distinct manner that, if used properly, is not open to misinterpretation. And when it comes time to generate the deliverable documents, the better modeling tools support generating the documents directly from the model.
Bottom line: modeling is more natural than text, will help you avoid and identify errors earlier, and still lets you follow your existing processes.
Use Case Diagrams, Actors and Associations
Let's talk a little more about actors.
Actors represent something outside the system that either affects the system or the system affects. The significance here is that an actor is outside of the system. You are not going to build it. You are not going to model its behavior. Even though UML and SysML use stick figures to show actors on diagrams, all actors are not people. Actors may represent people (for example, the user) or they may represent hardware (a sensor or an effector) or they may represent another subsystem.
Any of you who have attended any of my classes know that I am about to get on my soap box now. Hard engineering disciplines (electrical, mechanical, chemical, civil) will never take Systems and Software engineers seriously as long as we use these silly indicators and cutesy terms (e.g., fuzzy logic). Therefore, if you are going to show use case diagrams to your colleagues or customers who are not fluent in UML/SysML, change the picture of the actor to what it represents in the real world (a tank, a letter carrier, the physical actuator). Better modeling tools let you make this substitution (if yours does not, contact me and I'll put you in touch with a sales guy). OK, now I'll step off my soapbox and go back to the discussion.
When developing systems, actors represent anything you are not getting paid for. In an IT system, the actor may represent the server -- or better, an application running the server. In an aircraft flight control system, use an actor to represent the pilot (not the stick because it is part of the aircraft and generally falls under the auspices of the flight control subsystem), the inertial navigation system (it is not part of flight controls), and the surfaces (when you execute the model, you want to confirm they are moving the correct direction).
When developing software, use cases represent a single feature of the code (more on this when we discuss Use Cases and the Development Process). In these cases, the actor represents the other parts of the code that interact with that feature. Let me clarify. A reusable machine control framework includes the concept of generic inputs and outputs. No matter how the physical hardware works, the application interfaces with I/O using the same (virtual) calls. The use case Read_Discrete_Inputs has an association with a Client actor. This actor represents any part of the code that requires a discrete input. By definition, the Client is internal to the system, but it is external to the feature. Therefore, as far as Read_Discrete_Inputs is concerned, Client is external. In other words, your point of view determines internal versus external.
Associations show the virtual connections between actors and use cases. They indicate which use cases an actor affects and which actor the use case affects. Most, but not all, use cases have associations with actors.
Associations provide another purpose when reviewing the model. They indicate the potential interfaces. Specifically, the association between a User actor and use case indicates that the system requires some form of user interface -- a GUI, a push button, a retinal scanner. It forces the Systems Engineer to think about what may be missing from the overall specification.
One last point, in the early days of the UML, we showed associations as arrows. These arrows caused misunderstandings and provided little additional information. Therefore, I recommend that you show the associations without arrowheads.
Actors represent something outside the system that either affects the system or the system affects. The significance here is that an actor is outside of the system. You are not going to build it. You are not going to model its behavior. Even though UML and SysML use stick figures to show actors on diagrams, all actors are not people. Actors may represent people (for example, the user) or they may represent hardware (a sensor or an effector) or they may represent another subsystem.
Any of you who have attended any of my classes know that I am about to get on my soap box now. Hard engineering disciplines (electrical, mechanical, chemical, civil) will never take Systems and Software engineers seriously as long as we use these silly indicators and cutesy terms (e.g., fuzzy logic). Therefore, if you are going to show use case diagrams to your colleagues or customers who are not fluent in UML/SysML, change the picture of the actor to what it represents in the real world (a tank, a letter carrier, the physical actuator). Better modeling tools let you make this substitution (if yours does not, contact me and I'll put you in touch with a sales guy). OK, now I'll step off my soapbox and go back to the discussion.
When developing systems, actors represent anything you are not getting paid for. In an IT system, the actor may represent the server -- or better, an application running the server. In an aircraft flight control system, use an actor to represent the pilot (not the stick because it is part of the aircraft and generally falls under the auspices of the flight control subsystem), the inertial navigation system (it is not part of flight controls), and the surfaces (when you execute the model, you want to confirm they are moving the correct direction).
When developing software, use cases represent a single feature of the code (more on this when we discuss Use Cases and the Development Process). In these cases, the actor represents the other parts of the code that interact with that feature. Let me clarify. A reusable machine control framework includes the concept of generic inputs and outputs. No matter how the physical hardware works, the application interfaces with I/O using the same (virtual) calls. The use case Read_Discrete_Inputs has an association with a Client actor. This actor represents any part of the code that requires a discrete input. By definition, the Client is internal to the system, but it is external to the feature. Therefore, as far as Read_Discrete_Inputs is concerned, Client is external. In other words, your point of view determines internal versus external.
Associations show the virtual connections between actors and use cases. They indicate which use cases an actor affects and which actor the use case affects. Most, but not all, use cases have associations with actors.
Associations provide another purpose when reviewing the model. They indicate the potential interfaces. Specifically, the association between a User actor and use case indicates that the system requires some form of user interface -- a GUI, a push button, a retinal scanner. It forces the Systems Engineer to think about what may be missing from the overall specification.
One last point, in the early days of the UML, we showed associations as arrows. These arrows caused misunderstandings and provided little additional information. Therefore, I recommend that you show the associations without arrowheads.
Subscribe to:
Posts (Atom)