Questions asked about UCDF Software Diagramming and Documentation

top |

=== Blog ============================

You do not know what is in the code?
Is it old and messy?
All the developers left?
I can help!

=== Question =========================

Not sure what do you mean by software diagramming?

=== Answer ==========================

Making diagrams of your software, projects, and systems. Just like schematics in hardware, construction blueprints, and so on. Everyone can do it themselves, but they usually do not because, 1). it is a job, 2) they do not know UCDF method while other methods do not work well. Diagrams significantly improve productivity. Take a look: http://www.virtuar.com/ucdf/5398x3/kinds.htm

=== Question =========================

When to use diagrams, can I diagram my function?

=== Answer ==========================

Diagramming helps most when the code is intricate and your area of interest spans across multiple functions, modules, classes, or even projects.
A clearly written function does not require a diagram, the language itself with the help of good style of writing is designed to be illustrative.
Though UCDF can diagram on every level including operators, assembly, down to instructions.
UCDF is a universal method to illustrate all types of information processes based on idea that they are interchangeable flows of time (control) and information (data).

=== Question =========================

I am working on a small Delphi project, composed of two units. One unit is for the GUI, and the other for data management, file parsing, list iterating and so on.. I've already made a class diagram, and my workflow looks like hell- it's too complex, even for anyone to read. I've considered making a dataflow diagram, but it would be even more complex. A use case diagram wouldn't be of use either. Am I missing some diagram type which could somehow represent the relationship between my two units?

=== Answer ==========================

UCDF !

 

=== Question =========================

We're starting a project. Most of the functional specifications have been written, and there are a few features that will definitely be replaced with improved behavior in later stages of the project.
I'm tasked with writing a workflow document from a technical point of view and here's what I want to cover, ideally:

My attempts so far with Petri nets and UML interaction diagrams have failed upon the realization that I have to expose too much of the decision making logic inside controllers.
I'm looking for advice and I'm curious if anyone has done this before.

=== Answer ==========================

There is a well developed method for this purpose. It is called UCDF (Unified Code and Data Flow diagrams).
Functional-Code type is what you looking for.
It is perfectly suitable for close mapping of elements in the document with with models/views/controllers/js functions/other important blocks in the code.

 

=== Question =========================

I tried creating a flow chart of a function that I use in my program, but there are a lot of conditional statements in between every process and the diagrams are getting more confusing.
Is there a another language or markup other than flow charts that can be employed for large codebases with high complexity?

=== Answer ==========================

Use UCDF. Complex conditions are much easier to see than on the flow chart!

 

=== Question =========================

We have a lot of concepts in making diagrams like UML and flowcharting or just making up whatever boxes-and-arrows combination works at the time, but I'm looking at doing a visual diagram on something that's actually really complex.
State machines like those that parse HTML or regular expressions tend to be very long and complicated bits of code.
For example, this is the stateLoop for FireFox 9 beta . It's actually generated by another file, but this is the code that runs.
How can I diagram something with the complexity of this in a way that explains flow of the code without taking it to a level where I draw every single line-of-code into it's own box on a flowchart?
I don't want to draw "Invoke loop, then return" but I don't want to explain every last detail.
What kind of graph is suitable to do this? Is there already something out there similar to this? Just an example of how to do this without going overboard in complexity or too-high-level is really what I want.

If you don't feel like looking at the code, basically it's 70 different state flags that could occur, inside an infinite loop that exists to a label based on some conditions, each flag has it's own infinite loop that exists to a label somewhere, and each of those loops has checks for different types of chars, which then runs off into various other methods.

=== Answer =========================

UCDF method is exactly what you are looking for!
It is the method of diagramming the real code. Just real code.
Here is the example (a simple one though) and it is also about a parser:
http://www.virtuar.com/ucdf/2020/statemachine.svg
PS Your example is very clearly written and actually simple code. It does not even need diagramming. But diagramming is possible.

=== Question ========================

State machines?

=== Answer =========================

A state machine is not a model and it is not an abstraction. As soon as you develop code which models and controls a natural or technical phenomena, it will pass through several states, since all natural phenomena and technical systems have different structure under different conditions and exhibit different behavior at different times up to opposite. Any more or less complex code contains multitude of state machines not expressed explicitly. It is advantageous in software practice to express them explicitly. The analysis of real code must take it all in account and find what actual state machines lurk through an increasingly intricate web of data structures and operators.

It is an illusion that designers specify it all. Complex software behaves itself. Unexpected control and data feedback loops are born and deciphering them, if they produce undesired results, may take tremendous amount of time and effort. Clear diagrams may help.

Explicit definition of state machines in code is not always possible nor feasible, or just plainly not implemented. Without changing code, inexplicit machines still can be documented with UCDF.