How to visualize the design of a program in order to communicate it to others

Question

I am (re-)designing some packages for R, and I am currently working out the necessary functions, objects, both internal and for the interface with the user. I have documented the individual functions and objects.

So I have the description of all the little parts. Now I need to give an overview of how the parts fit together. The scheme of the motor so to say.

I've started with making some flowchart-like graphs in Visio, but that quickly became a clumsy and useless collection of boxes, arrrows and-what-not. So hence the question:

• Is there specific software you can use for vizualizing the design of your program
• If so, care to share some tips on how to do this most efficiently
• If not, how do other designers create the scheme of their programs and communicate that to others?

---

Edit: I am NOT asking how to explain complex processes to somebody, nor asking how to illustrate programming logic. I am asking how to communicate the design of a program/package, i.e.:

• the objects (with key features and representation if possible)
• the related functions (with arguments and function if possible)
• the interrelation between the functions at the interface and the internal functions (I'm talking about an extension package for a scripting language, keep that in mind)

So something like this :

But better. This is (part of) the interrelations between functions in the old package that I'm now redesigning for obvious reasons :-)

PS : I made that graph myself, using code extraction tools on the source and feeding the interrelation matrix to yEd Graph Editor.

Answer 1

Is there specific software you can use for vizualizing the design of your program

Where I work, we use Visio, mostly.

If so, care to share some tips on how to do this most efficiently

With flowcharts, for program flow. For program organization, UML-like (probably not strictly conformant to UML standards, but no one's too worried about that ;) ) diagrams are used.

For diagrams as complex as yours, using a tool to generate a full-system diagram such as this might be a good starting point, just to get a feel for what things look like, but I'd suggest breaking it up into many smaller diagrams, maybe one for each subsystem, which you seem to have surrounded with a box. Links to other subsystems should not point to the modules within those systems, just the name of the subsystem. In fact, I think in Visio it's even possible to create links between diagram pages so if someone clicks on the link that goes from one complex module to another, they'll be taken straight to that module. It might also help to create a diagram at a higher level - something that shows the interactions between each subsystem, and ignores each lower-level module.

I'd follow a similar divide-and-conquer strategy for flowchart diagrams of this system.

Trying to diagram a system this large in a single diagram is difficult and if the result is too complicated, it might well be useless. I have seen it done, but it's difficult to get it right, and they had to print it on special poster-sized paper for it to be readable. It was posted along 4 corridor-facing cubicle walls and it got annoying when a pack of analysts would gather around it discussing possible changes and impacts. By the end of the project it was covered in pen, pencil, and highlighter markup...

Answer 2

UML is a very strong option for representing programs graphically. Grady Booch and a team of others wrote a great book called Object-Oriented Analysis and Design with Applications that introduces OOAD pretty rigorously by spending around 150 pages discussing concepts before diving into notation. While in someways the diagrams are easy to comprehend without much training, Booch is a master at defining ideas like complexity, distinguishing between object model and class model, and classification. The advice about complexity includes discussion of several tools like algorithmic decomposition, object-oriented decomposition, abstraction, hierarchy, and encapsulation.

It is important to remember that you may need to look at your software from several perspectives so that you can capture the static structure and dynamic behavior of both objects and classes. A class diagram would capture the static structure of one or more classes while a sequence diagram would capture the dynamic behavior of two or more objects as they interact. Booch also breaks things down into categories structural, behavioral, and interaction diagrams.

UML Diagrams

• Structural
  • Package
  • Class
  • Component
  • Deployment
  • Object
  • Composite Structure
• Behavioral
  • Use Case
  • Activity
  • State Machine
• Interaction
  • Sequence
  • Communication
  • Interaction Overview
  • Timing

For anyone who can name only three or four UML diagrams this should be a wake up call. If you spent a day or a few hours a day for a week, you might not know UML very deeply. Often, UML is taught as a four day course, and sometimes as three or four days for object oriented analysis followed by three or four days of object oriented design. University courses may teach it as a one or more semester courses, or fold it into a sequence that used to follow the waterfall software life cycle (requirements and analysis (with use cases), software architecture and/or design (with the remaining diagrams), object oriented programming (with Java, C++, etc), and testing (that revisits use cases or state diagrams)).

Martin Fowler has a book that I like called UML Distilled where he essentially lays out a pattern for each diagram type, listing it name, a brief description, samples of the diagram and what the arcs, nodes and decorators mean, and most importantly, when to use them. In his introductory material he describes UML as having three applications: to make a software blueprint, as a higher level programming language that generates code (or sometimes reverse engineers from code, or transmutes forward and backward in round-trip software engineering), or my favorite, as a sketch that helps communicate between developers some localized and specific aspects of the design.

UML haters are right about a lot of things. For example, about how much overhead can be involved in using UML to document a design (in blueprint or programming language mode). They sometimes say, a fool with a tool is still a fool. It is a bad idea for an under-trained developer to jump in a make diagrams just as it is for a FORTRAN programmer to start writing in C++ or Java from a table that shows which statements are equivalent. With a UML diagram editor of Computer Aided Software Engineering (CASE) tool (CASE has endured a lot of criticism) it became possible for bad designers to make big bad designs much faster.

UML lovers will point out that it allows us a common language to communicate our design in a visual and expressive way. As we represent the same design in multiple ways, it gives us a great rehearsal for the code we will write. Because it is visible it facilitates a form of communications with others that is faster (we process visual information much faster than verbal, and by indirection, than text), and gives us many opportunities for peer review. Because we use more than one view, it permits us to move between hierarchical views like deployment diagrams, package diagrams, and class diagrams. We can see the same information at rest in the object diagram, and in motion in the activity diagram and sequence diagram. By using related diagrams, we can reveal problems with completeness and consistency early, and sometimes use a representation that is easily generated like a state diagram to discover needed content in another diagram like a sequence diagram.

Answer 3

There are a variety of tools to convey the design of a program in general. Tools like UML and Object Diagram should be sufficient for you.

Also include comments in your code as and when needed.

Answer 4

Separate the graph into multiple simple, smaller ones. One should be a general overview of the key parts, another would show the interaction between two or three parts, then a graph showing one module in detail. I personally prefer hand drawn non-formal graphs.

Each should come with a textual description and reasons behind the (re)design. Creating a FAQ at the end of the document could be helpful too (try to collect questions from people who are encountering the system for the first time).

Answer 5

Granulate the application flow and prepate a work flow diagram. Or go for sequence digrams. Flow charts good for expressing the logics; not for app design