Related
Is there a formal language which can be used to capture the information present in an UML sequence diagram in to a text format, which is easy understandable by humans?
In our place, often times software requirements are specified in terms of complex sequence diagrams which are difficult to review, verify for correctness and make changes. Also IMHO, programmers would prefer to implement from an unambiguous text representation of the requirements, rather than from sprawling multi page diagrams.
(1) Yes, there is a proprietary almost formal text format language able to express information in UML sequence diagrams understandable by programmers (and may be also by some other humans).
The language I mean was designed and implemented by Steve Hanov, comprehensive list of examples is available at https://www.websequencediagrams.com/examples.html and I have emphasized one of the examples below so that you can get the readability idea:
(2) But, beware that you (or someone else) can write bad, unreadable, code in any language (textual or graphical) and changing the language will not automatically change your (or someone else's) habit's an make the code automatically better, more readable, more maintainable
(2.1) Writing down "unambiguous text representation of the requirements", e.g. in the form of use cases approved by the client is not an easy to-do nor easy to-learn thing and just a language change will not improve it much. (see e.g. Stack Overflow: From user stories to sequence diagram for some more pointers)
(2.2) intended audience (readers) for the UML sequence diagrams are not only programmers but also less technical stakeholders for whom a picture may be worth thousands of words . In my opinion, giving programmers Java pseudo code which can be even reverse-engineered into UML sequence diagram by a tool if needed (see Stack Overflow: how to generate sequence diagram from Java source code or Google: "java sequence diagram" for some more pointers) is better then trying to find/invent a sequence-diagram-specific language
(2.3) there are certainly tools that aid reading large UML designs by using tricks like zooming, hyperlinks, collapsing/expanding blocks, tuning the displayed level of detail and there are paper sizes like A3 or A2 which can turn typical multi-page diagram into single-page diagram
From your description it seems that in your place you have process problem and you'd better ask a question at https://softwareengineering.stackexchange.com/help/on-topic
What topics can I ask about here?
Programmers Stack Exchange is a Q&A site for professionals and students in software development and related fields who are interested in getting expert answers on conceptual questions about software development.
If you have a question about...
software requirements
software architecture and design
...
development methodologies and processes
software engineering management
...
xmojmr's approach is an effective way of documenting use case scenarios, and if your sequence diagrams are confusing, it's probably because they aren't adequately documented. As xmojmr says, a picture is worth a thousand words, but sometimes a few hundred words really help to explain the picture! I'd like to share a bit of background that you might find helpful.
I see the process of describing requirements as having three levels, of which use case scenarios are the third. Top level is a use case diagram, which shows how the different use cases in a system and the stakeholders using the system interact. Next level is the details of each of those use cases. I use a "use case narrative" for this. Third level is each individual path ("use case scenario") through a use case.
There is a lot of confusion out there between levels two and three. This is partly because to some extent they run together, for example it's reasonable to analyze related success and failure paths through a use case as one scenario rather than two. At least, I prefer to treat them as one scenario.
I prefer to use activity diagrams to document use case narratives. While you can pretty much do anything with a sequence diagram (at least the 2.0 version), IMO divergent behaviors, decision trees, and parallel behaviors are more obvious in activity diagrams than in sequence diagrams. So, one activity diagram per use case, and then one sequence diagram for each separate scenario in the use case.
In your process, it looks like sequence diagrams are not accompanied by formal use case scenario documentation. If you google "use case scenario" you will find a number of examples of such. However, keep in mind that a lot of the examples are actually documenting what I'm calling "narratives".
I'm using the terminology in Tom Pender's The UML Bible (Wiley Publishing, 2003). Another great book is Alistair Cockburn's Writing Effective Use Cases: here is a good-sized sample.
another online text to diagram tool which is using a similar syntax.
http://echoma.github.io/text_sequence_diagram/
I often draw a dataflow on a sheet of paper. Even the planning of my little tools is done on a paper.
There exists UML.
The problem is - I don't like it. All the tools I've used (Visio and a lot of online editors) are just not flexible for my hands. With a pencil you can easily draw shapes and connect them, describe them.
What could you suggest in order to create a diagram of data-flow, sequence diagram, etc. in the fastest, most natural and easiest way except on the computer not the paper :)
****Useful links as posted in comments:** SO Link #1 SO Link #2
Right now I am curious about 2 things and one of them was in my minds quite long ago:
1) Mindmap - I've tried a while ago, quite liked it but abandoned. Hoever will give it another try
2) Whiteboard. It would be the easiest and most natural method, except that taking a photo and storing it somewhere on a computer would make the process repetitive and boring.
Has anyone other interesting ideas? I would really like to hear what others are using to design their software and the progress of it.
Thanks a lot!
Why do you want to hand-draw the UML at all whether it's on paper or on the computer?
I agree that you need a model to represent the design. But even in large projects of about 500 man-months, I observed that only 3-4 sequence diagrams really matter and have a chance of surviving the entire lifecycle of the application. Those 3-4 sequence diagrams (and class diagrams that represent their static time relationships), usually represent the high level design of the application.
Or, look at it this way:
Any decent enterprise application will not have 20 different call flows. There will be one or two generic (or abstract) call flows, which all the concrete use cases implement. Let us take a simple Struts / EJB application. The generic flow will be something like - an action class calling a validator and then calling a stateless session bean, which in turn calls a domain class, which will call a DAO. All the use cases of the application just implement this flow with concrete classes that are specific to that use case.
Do you agree?
If you do not, I would like to hear about applications that have 20 different call flows and survived for 5 years after the first release.
If you agree with me, we are boiling down to 3-4 class and sequence diagrams even for large enterprise applications comprising several thousand classes. Why is it a big deal how you draw and maintain those 3-4 diagrams?
You might say that you want to document all the use cases for training or documentation purposes. During my last 14 years of experience in the real enterprise software world, I don’t remember seeing well 'maintained' UML documentation. First of all, good documents are difficult to produce and are not found that often. Secondly, they are out of sync with the code most of the time. Most of my experience is with large banks, insurance companies, Auto companies, etc. Those environments are just too hectic and their resources are limited (really? Are we talking banks? Yes, difficult to believe, but true) for 'maintaining' good documentation.
So am I suggesting that we get rid of UML?
No. We need visual models to represent complex systems. Human brains seem to be at their best when processing visuals. The visual cortex, which is responsible for processing the visual images, is the largest system in the human brain.
So what is a reasonable solution to easily produce and maintain UML models?
Probably we are better off using the current crop of UML tools to draw those 3-4 high-level UML diagrams. If you hate using them, check option 3 below.
For the diagrams at the next level of abstraction (any useful models should have different levels of abstraction), generate the UML from source code. You can generate both class and sequence diagrams.
In this age of agile methodologies, why not just write the shell classes and generate those 3-4 high-level UML class and sequence diagrams as well? This way there won't be any UML to maintain at all.
The source code is the truth.
Can you argue against that statement? If not, why not generate the models from the source code itself? I am not suggesting the round-trip engineering, by the way. I am just suggesting a one way trip - from code to models.
There are 2 main problems however with the generated UML.
When we hand draw a class diagram, we show the relations between the classes involved in a scenario. Most existing class diagram generating tools allow the user to drop the Java classes (the source code) into the tool and the tool automatically shows the relations between the classes. The problem here is, how does one know about the classes involved in a scenario to begin with?
The second problem is the verboseness of the generated diagrams. There are tools available to generate runtime sequence and class diagrams for a scenario. But the diagrams are often very verbose and defeat the purpose of models, whose purpose is to highlight the important aspects and filter out unimportant details.
Good UML generating tools should address both the above problems. There are a few tools in the Java domain that try to address these problems. Check the discussions below:
What tools should I use to visualize structure of my code
Are there any tools for detecting architectural and design patterns in code?
I hope I answered the original question:
Has anyone other interesting ideas? I would really like to hear what others are using to
design their software and the progress of it.
I am the author of the runtime UML generating tool MaintainJ, but I tried to address the original question in an objective manner. Your comments are welcome.
There are various tools that allow you to create diagrams based on textual input. There's some up-front learning in that you need to learn the syntax. However it's not hard to do. Once you have, creating diagrams can be very fast. There are some downsides; in most cases there's limited ability to change the layout/style. Significance of that will depend on whether you like their style or not.
There's a growing number, here's a few you might want to look at:
UMLet: desktop app, supports most UML plus various other diagrams. Can also create your own custom shapes & connectors. FOSS.
WebSequenceDiagrams.com: online sequence diagrams.
TextUML: desktop app. Focus is executable models, auto-generates class diagrams. FOSS. It also has an online commercial sibling.
hth.
I like using a whiteboard and a camera. For even more flexibility, use post-it notes on the whiteboard.
I use ER diagrams (on the whiteboard) to model my data, and message sequence charts (on the whiteboard) to model the data flow. I'll also do quick mockups of UI pages on the whiteboard.
Asides from that, I use Ruby/Rails to code server side and HTML/CSS/jQuery/JS on the client.
If even Visio is not flexible enough, I'd suggest a digital whiteboard or touchscreen with a whiteboard software. After some accommodation you could probably use a simple tablet (without display) as well - they are really cheap.
Regarding pure software: we are trying to achieve a "pen-like" input method with UML Lab, but it currently supports Class Diagrams only...
I think that the UML and code should be mixed using a class diagram. You model your architecture with the class diagram (e.g package, classes etc....) then you code your business finally multiple iterations between code and model.
I think that UML should more be oriented to code but not to focus on textual input.
The problem with standard languages, such as UML, is that you have to invest a considerable effort to learn the language and the modeling tools. These languages are defined by an expert consortium, e.g. OMG, that proposes a language specification suited to the biggest overlap of design problems in a certain domain.
Why not defining your own language that fits exactly to your needs and your specific problem? Such languages are termed Domain-Specific Languages (DSL). Instead of investing into learning a language that's complex, you invest into the definition of a languages that exactly suits your needs.
There are numerous approaches that support the definition of DSLs. The most widespread is the Generic Eclipse Modeling System (GEMS). Personally, I made great experience with GrGen due to its versatility and the possibility to automate working steps using graph transformation.
No. There are various other ways. UML is just an option.
Pen and Paper Prototyping is a great option too, it doesn't have to follow UML.
Mind Map is another great way.
For more adaptive software processes, UML use is encouraged to be as minimum as possible. Such as, teams that practice Agile or XP tend to use UML less and they would rather rely more on informal means to conceptualize the software. In a rigid structured company, UML can be rigorously followed.
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.
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?
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.
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]
I have seen UML mentioned several places in the last few years, but never had a compelling reason to use it at work so far. Is there any value in putting the time and effort to learn it? (I am a Ruby on Rails developer.)
Edit: I'm also looking for stories about how UML has made a difference in your projects to give me an idea of how I might use it.
Yes. It is the international standard methodology for systems analysis and design. When moving from the initial analysis phase through the project life-cycle, the UML gives a good road-map on where to go and how you got there. A few benefits:
It shows requirements in a way that clients / customers / management can understand.
You can iterate the model and not lose track of where the model was before
Shows exactly how you got from point A to point B
It's a standard, so anyone who knows UML will be able to interpret your diagrams
The "quickest" way to share ideas without needing to go through the entire code-base
No, save your time and don't learn it. If you are a coder and work alone and are a very careful person, you can completely ignore UML.
But, if you work with other people and want to share the result of your work, UML is a Unified language, a lingua franca that even non technical customers understand (at a certain level).
Yes and no.
Yes, learn the basics. Have a quick look at at the different diagram types etc. and have a general idea. That will help you eliminate your hesitance when someone boasts about UML.
No, if your work doesn't require to work with UML, you don't necessarily need to know UML to write good applications. If you need to discuss something on a white board just draw a few circles. That'll do.
It only helped me to produce documentation to management to impress them a little. Other than that I only find the deployment diagrams somewhat useful, that's all.
If you look at UML as a merely graphical language you consider just a very small part of it. You should instead look at UML as the primary language of the Model Driven Architecture framework which is very well implemented in Eclipse.
In Eclipse UML is (correctly) considered as a Platform Independent language with a solid syntax defined by the MOF (ECORE in Eclipse) and semantics defined by the UML specification (http://www.omg.org/spec/UML).
In Eclipse there are good implementation of the two main languages defined by the OMG for Model To Text and Model to Model transformation specifications which are respectively MOFM2T (ACCELEO in Eclipse) and QVT.
Also Eclipse provides an implementation of the Object Constraint Language (OCL) which is used by both QVT and MOFM2T to evaluate queries on models.
All this means you can easily define your own Model to Text and Model to Model transformations , in the form of Eclipse plugin, turning your UML models into whatever you need.
Now I use that to automatically generate thousands of LOC, documentation and tests with an impressive return on investment.
However I know the majority of people doesn't even know UML is a language but think it is just about tiny pictures.
Look at this links for some simple example
http://lowcoupling.com/post/46522537374/the-model-driven-architecture
http://lowcoupling.com/post/47800863669/qvt-in-place-transformations
http://lowcoupling.com/post/47347056110/models-to-text-transformations-with-mofm2t-and-acceleo
I think it's a question of scale in two dimensions: size of problem and size of team.
When a design gets to a certain size diagrams become useful in two ways: first, they help you reason about design issues. second they help you communciate the design to other poeople.
So if the team is say 20 or 30 it really does help to have some clear documentation of pieces of the overall design.
Personally I use UML maybe four or five times a year, but when I need it, I really need it. It really is better to ase a standard diagramming technique that devise your own. And with good tools it's pretty painless.
I would say that I use only a small subset of UML, class diagrams and occasional collaboration diagrams.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
What diagramming technique(s) do you use while programming to help you
or others understand your program or design. I am not talking about a person's
favorite tool, though a good tool probable helps a person greatly with
diagramming.
My intent in this question is to find the simple useful diagramming techniques
people actually use and find new ones to learn.
Do you use flow-charts, Data Flow Diagrams, ER diagrams, etc?
The web is full of recommendations! But what do real programmers, designers,
and code maintainers actually use in their day to day work.
Thanks for your feedback
Very High Level Discussion - Context Diagrams where the boxes might represent classes, packages, or sub-systems.
High Level Design - Sequence diagrams which show the interface between sub-systems, still no classes directly used but may be implied from this.
Detailed Design - Sequence diagrams which are at the class level.
If there is a tricky algorithm for something such as the correlation of multiple data streams into a new stream then I will generally use a Flow Chart to work out the algorithm.
If the solution requires knowledge of state then a State diagram is also used.
Those are the ones I use most.
When doing Data Warehouse design I draw Star Schemas to work out how to store the data. When doing Transactional DB design I use Entity Relationship diagrams to work our data storage.
When designing a UI I just sketch it out. Once I start to get some parts of the UI worked out and want to play with some areas I will make a template, print out a copy copies and then use that as a guide to work on sub-sections. For colour schemes, it can be handy to make a graphic using the gimp and have layers for each piece of the design and then play with the layers colouring each one to find the right balance.
What do we really use? Maybe other people actually create formal diagrams, but for the most part I just scribble bubbles, boxes and lines on a sheet of paper.
I use a whiteboard for modeling, so I guess "whiteboard modeling language" would be my answer.
I will do a UML Class diagram for anything i'm designing that is bigger than a couple of classes. Drawing a class diagram makes me take time out to think over the design instead of ploughing straight into the code and always produces a better result.
For bigger and more complicated architectures I find that Sequence diagrams are a good way to communicate behviour, especially for multi-threaded systems.
I use diagrams as a way to quickly understand legacy code. It takes some work to create the diagram, but it always pays of in the end.
Normally I use class diagrams to get the big picture. Sometimes sequence diagrams and even dataflow diagram if a piece o code is extremely hard to understand.
In the design phase I use class diagrams, and often state diagrams. State diagrams are perfect if a class behaviour differs with its state.
I use Sequence Diagrams a lot (drawn on paper). I find they give me a nice visual representation the logical flow of method calls and information between various systems and components in our applications.
I have a Flow chart of the main product I work with and develop.
My team also often uses UML diagram sketches on white-boards while designing new parts for us to implement. They're very useful in creating design patterns and modeling the high-level structure of the classes which will be needed. These are never full blown UML though...
Whiteboard for discussions.
Pen and paper for less temporary record.
Code stubs for 'Things to impelement'.
Tested and Working code (with extensive comments) for posterity.
I use ER and class diagrams on paper and whiteboard for any project that's bigger than a shell script.
Flow charts, only when I need to explain a process to a non-programmer (or if it's a really complicated process and I need to understand it first).
My old boss used to say "the guy just loves drawing stuff."
I work in an AJAX development environment, and most of the backend code I write works like a pipe between a relational database and the frontend javascript (user interface). So, the most used 'diagram' per say that I use are JSON objects to describe how data should be passed back and forth between the database and the interface. They are simple, universal and easy to understand data structures.
Example:
{
"id": row['id'],
"name": row['name'],
"mandatory": row['mandatory'],
"rangeDescription": "This is the Range",
"globalRate": row['global']
}
I draw bastardized versions of UML class, object and sequence diagrams. While I try to be true to the syntax, I am much more concerned about expressing the main idea behind particular feature. So, I'll draw up something, ask a colleague to take a look, and if it seems clear enough, we might even scan it and post it in our Wiki.
Then, when it so happens that we actually get some time to work on the documentation (and that is almost never), I'll use BOUML and redraw the scribbles into a proper diagram.
Now, to put is all in context, I'm working at a relatively small team (5 developers), making trading and product configuration platforms in Java. We have our two products that we then additionally customize to customer's requests. Being a close-knit community, with low (zero) turnaround for a few years, we use the documentation primarily as a remainder to ourselves. And in this setup, the above approach works quite well.
I like Data Flow Diagrams. A lot.
I use whatever is needed for communicatation. Usually that's nothing at all. Sometimes it's a whiteboard.
From time to time, I use Sparx Enterprise Architect, which is a UML modeling tool, though it produces decent diagams while it's at it. I've used it for requirements, use case, activity, sequence, domain, and even class modeling, and sometimes some reverse-engineered ER diagrams. Whatever it takes to get the point across.