Home > On-Demand Archives > Theatre Talks >
Express Your Software Ideas Graphically
Jean Labrosse - Watch Now - Duration: 31:54
Today’s code editors are very powerful tools that offer syntax highlight, code completion, versatile search, variable browser, function browser, hover-over and jump to declaration/definition, etc. However, even with these amazing features, you are still staring at a few hundred lines or so of source code, putting you straight in front of a proverbial tree thus missing the view of the forest.
There are literally dozens of software modeling methods and methodologies, yet many embedded software developers jump directly to the coding aspect, often bypassing an important step that would help you understand and document the structure of an application. That being said, I’m not trained in most of these formal methods however, I use graphical techniques adapted to software from my Electrical Engineering background.
This class will explore some of the techniques that served me well when designing and architecting applications. As simple as some of these techniques might be, they have helped me develop complex applications.
Thank you for the talk. I also use schematics a lot, especially finite state machines and UML's sequence diagrams, to explain complex interactions between modules.
A tool that I find interesting, as it is free and web-based (there is also a computer application): https://app.diagrams.net.
Hope this will be useful!
Interesting indeed. Has this been around for a long time? Are there regular updates? Hope it remains available for years to come.
I heard about this tool two years ago. As I am using web app, I do not know if there are frequent updates. I did not noticed any change so far, except the address (It was peviously named draw.io)
Thank you for the talk. It was nice to see that you use/d some of the tools I also use/d. I am involved in both embedded systems and digital design (FPGA). If in the embedded world the graphic is used to complement the code design and for a better documentation, in digital design graphics are used more in the design process. I saw designing tools going from graphics (logic gate diagrams) to code (hardware description languages) but never dropping completely graphics. Even the newest tools make use of graphics to create high-level block diagrams that allow to have that 50000 feet view of the design, so for better understanding all the relationships between components and signals going in and out of them.
In old versions of Xilinx ISE tools there was a graphic tool named StateCAD used to draw FSMs from which your could automatically generate Verilog or VHDL code. I don't know why they dropped it.
I also use graphviz to draw FSMs or other diagrams that can be built with this tool. The reason is because I can generate the diagram from a text file that can be quickly written with any text editor and can also be easily modified or reused (which means an increased productivity) - drawing with the mouse is also possible, but it is much slower. As you said, a picture worth a thousand words but if you can draw it base on a few lines of code, it is even better.
Thank you for attending and for sharing your thoughts. I'll check out GraphViz as it sounds like a neat tool.
A good talk! Thanks!!
Thank you for attending.
Hi Jean Labrosse,
Thank as lot for your presentation. It was very insightful specially because you gave us a very broad overview of current tools that can help us in "visualize the software".
My "addendum" here is regarding the possibility of interacting visual descriptions of the source code using Doxygen as was discussed by you and some of other peers.
There is an interesting (but still very simple) extension to Doxygen called Moritz that generates Nassi-Shneiderman diagramms of functions and methods in a C/C++ source as html files, which could be included in a software documentation or just watched by using a browser:
https://sourceforge.net/projects/moritz/
In addition, something extremely useful would be a tool that could visualize not only classes, functions, objects, variables, etc but also the flow of data inside a large software application.. ;-)
Best Regards from sunny Japan,
Wilson
Thanks, I?m sure others will also find this useful.
Good talk. I've used Vizio for memory maps and similar diagrams, but for documenting state machines, flow control, and communications links, I usually used graphviz. It's not hard to process a state machine implemented as a table to produce the necessary graphviz statements. Depending on the language, call dependency graphs are also not that hard to produce automatically.
Thanks for all your advises. I liked the ISR and Task diagrams. I like document all, however sometimes there isn't time to make that. Additionally, I use doxygen (https://www.doxygen.nl/index.html) for obtain the documentation from the code.
Well, as far as I?m concerned, the diagrams don?t have to be pretty, hand drawn works fine if that?s something you can put together quickly.
I?ve used ?Doxygen? . It?s better than nothing but it still remains to be only text and it doesn?t give you a 50,000 foot level view.
What is your suggestion about SW documentation? (Except Doxygen)
UML, is it suitable?
Well, Doxygen is fine especially to avoid having to duplicate the documentation of APIs. If you can add URLs to illustrations or further explanation of those APIs then it would augment the usefulness of the code's documentation. Of course, you would have to maintain the illustrations but at least they would be linked to the code.
A lot depends of what your code is used for and who the audience is. In my case, my 'product' was software modules so it was important for me to make sure users would have as much information about our products so they can make good decisions when using such software. If the documentation is for internal use or simply yourself, I'd say do as much as you believe you will need to be able to either understand it yourself down the road or, enough to be able to pass along to someone else. Of course, we are all subject to tight schedules and market pressures and unfortunately, 'documentation' is almost always the first to be thrown out the window.
I haven't used UML so I really cannot comment. All I can say is use whatever helps you or your team. If your team is trained in UML and they understand it then you use that. I look at this like coding standards, something is better than nothing!
Of course Jean... I will work on that in my next project... Thanks
Jean,
Thank you for your talk. I make extensive use of diagrams in my design work, and also when deciphering legacy code. It was helpful to see how you do it, and I learned of some new types of diagrams and tools which I was not previously aware of.
Most of the diagram tools that you presented about have graphical point and click interfaces. Do you prefer this kind of interface over text based tools like plantuml?
Thanks,
Sean
Sean, Yes, I prefer point and click interfaces. That being said, I?m not familiar with PlantUML ?
? Just looked at a couple of videos on YouTube. Quite cool, certainly another tool in one?s arsenal.
Thank you very much it's always a pleasure to listen to your informative talks. I also think that it's the best approach for starting a development by drawing some "big picture" diagrams. Especially if you as as en embedded engineer are new to technical domain. These graphical approach is really helpful to close the gap between the domain experts (who know what to do) and the embedded developer (who knows how to implement it). At the very end you mentioned the problem of keeping source and documentation up to date. To me some "best practices" for this would be another interresting topic to hear about. As long as a project is in time this is nothing care about but when deadlines arrive i heard so many times "features are more important than documentation". And in the end if your product moves from development stage to life cycle mainainance you pay the price for this.
Erwin,
Thanks for the feedback. I?ve mostly seen younger Engineers just wanting to go to code because that?s the fun part. I think the fun part is to ?see? a design without having code. The code, IMHO, is the easy part, once you understand the big picture. The less fun part is, to me, the debugging stage which a lot of that can be diminished using these techniques.
And your last comment, my answer is: ?There is never enough time to do it right, but you will be given the time to do it over!?
I really enjoyed your talk as it was also very practical. In respect to the tools you used there is also need to update those regularly or convert the visual to a different format. Over the years lots of tools vanished or run only under old OSs. This adds additional amount of work for documentation. Thank you also for sharing the slides (which I wasn't aware of so I took handwritten notes). This was a great presentation which I liked very much. Thank you!
Thomas,
Thanks you for you comments. I agree that some of these tools go obsolete over the years. Hopefully, the longevity of the tools is more than the lifetime of the embedded product (which is not always the case). I used these tools to mostly help in the design and pass information to others that would inherit the software. My point is mostly to say that textual description or code itself is not very good at providing an overall 'picture' of an application, especially a complex one.
Glad you enjoyed the talk.
Jean
Very relevant. What about UML? Diagrams are excellent, but even better if semantics are standardized. The Entity Relationship Diagram (ERD) is a lovely basis for a semantic model for implementation and analysis. Visual Paradigm may be an interesting tool as they support ERD and state models (including composite state models) across multiple platforms: https://www.visual-paradigm.com.
Thank you!