Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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 :

enter image description here

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.

share|improve this question
1  
1  
I've personally found simple english explanation to be the most effective way of communicating this stuff. If you're talking about a whole module/package structure I find it best to just touch on each piece of it with explanation of purpose and use case. Something small for each piece, then you can do long drawn out explanations for each piece further down if you wish to go into detail about the reasons. I do not personally find diagrams for software hierarchies to give information about purpose and use, just relationship which is not useful without knowledge of purpose. –  Jimmy Hoffa Oct 15 '12 at 14:26
2  
@JimG. No, that one is about software usage, this is about software design –  Jimmy Hoffa Oct 15 '12 at 14:28
    
@JimmyHoffa I've added a bit more explanation. I know that writing it up in a big document is the best way, and I've done most of that. But my boss doesn't like to read many pages... –  Joris Meys Oct 15 '12 at 14:34
    
@JorisMeys That's why I said a very small explanation for each piece, the whole shouldn't be more than a couple pages, then you can have a 200 page white paper follow those couple pages where you give in depth explanation of the origins of the universe and how it lead to your module being made. –  Jimmy Hoffa Oct 15 '12 at 14:36

6 Answers 6

up vote 4 down vote accepted

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...

share|improve this answer
    
I've been fiddling with Visio for a long time now, and never really got out what I wanted. Any pointer to a tutorial on how to make UML-like diagrams in Visio? The closest I came was using database diagrams, but that makes it difficult to distinguish between objects and functions. And as R is a functional language, that is rather important to do... –  Joris Meys Oct 15 '12 at 15:12
    
@JorisMeys: I've never worked with R so I'm not sure pure UML diagrams are the best option... BUT Visio can let you mix shapes from various types of diagram sets. For a new UML diagram, you can do "File -> New -> Software -> UML Model Diagram (Metric)" - assuming that shape set is installed. Or if you have a blank diagram, you can choose any shapes by "File -> New -> New Drawing" and then "File -> Shapes -> Software -> (any shapeset you want)" –  FrustratedWithFormsDesigner Oct 15 '12 at 15:22
1  
Later versions of Visio come with UML templates (stencils), or you can use Pavel Hruby's custom stencils. Martin Fowler has some interesting thoughts on his bliki. –  TMN Oct 15 '12 at 15:26

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.

share|improve this answer
    
Forgot to thank you for this elaborate piece of great information. Made it up now :) –  Joris Meys Feb 2 at 14:59

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.

share|improve this answer
    
Thx for the pointer to UML. I've never really given it a try, but I'll look into it. –  Joris Meys Oct 15 '12 at 15:13

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).

share|improve this answer

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

share|improve this answer

I am using processing.org (Java) to model gene networks. This is essentially documenting DNA based software using a node diagram originally used to draw relationships in cell phone networks http://alignedleft.com/work/relationship-visualizer.

I replaced the cell phone numbers with genes (DNA software) and built a weight based model to analyze relationships between genes in cancer. I am experimenting with a model for stem cells. http://nextbigfuture.com/2014/01/simple-acid-bath-can-turn-blood-cells.html#more

share|improve this answer
1  
Could you elaborate how the OP could use this to visualize the design of their program? –  Martijn Pieters Jan 30 at 17:34
    
Graph Databases may be used to store relationships that can be displayed.it-ebooks.info/book/2329 –  Henry Brown Feb 11 at 18:05
    
Use processing as a graph database display tool could allow complex networks to evolve with a memory. CRISPR is used by bacteria to store viral memories.en.wikipedia.org/wiki/CRISPR –  Henry Brown Feb 11 at 18:10
    
This may be a method of documenting context switching in bacteria. This could represent the earliest intelligent system. Could this be the basis of all bio intelligence? –  Henry Brown Feb 11 at 18:13
    
Don't post all this in comments. edit your answer instead. –  Martijn Pieters Feb 11 at 18:15

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.