Visual software development through diagrams and other visualizations was a dream that persisted for a long time in IT, but never came true for any software platform. Yes it is true that UI design or database modelling can be very visual these days but the main bulk of any serious software project remains as of this day primarily text based. There are many reasons for that, but I don't want to discuss them here. Instead I want to express my opinion that despite the apparent lack of progress in this area, the visual expression of any abstract concept for most people makes it much more easier to grasp. So perhaps we should make more steps in that direction, even if we cannot turn the whole programming into a visual work yet.

I remember a few days ago I had to go back to an old project and review a piece of code that I have written several months ago. The task was not very easy to understand so I decided to draw a diagram that shows the different states of the code execution. When I finished that I was quite shocked because I realized that if I had this diagram in front of me on the first place it would have taken me just seconds to remember the concepts behind that code.

At that point I realized that if I can organize a solid integration process between my code and visual diagrams depicting the abstract concepts behind that code I would increase my productivity quite noticeably. To make my idea more clear I can show a simple snippet of code that is not a trivial code for non functional developers. I consider non trivial to be any code that requires more that 5 seconds to understand. Something that is not trivial for you today may be quite trivial tomorrow, or something that is trivial for you may be non trivial for a more junior developer in your team, and most importantly if something is trivial for you now when the project is fresh in your head it may become non trivial after 6 months of working on a completely different project. Anyway, so my example code is the following one:

public static TAccumulator RightFold<TSource, TAccumulator>(
                              this IEnumerable<TSource> enumerable,
                              TAccumulator state,
                              Func<TAccumulator, TSource, TAccumulator> process)
{
    //<diagram#53>
    using (var e = enumerable.GetEnumerator())
    {
        Func<Func<TAccumulator, TAccumulator>, TAccumulator> inner = null;
        inner = continuation =>
        {
            if (e.MoveNext())
            {
                var current = e.Current;
                Func<TAccumulator, TAccumulator> innerCont =
                      accumulator => continuation(
                                        process(accumulator, current));
                return inner(innerCont);
            }
            return continuation(state);
        };
        Func<TAccumulator, TAccumulator> justReturnArgs = accumulator => accumulator;
        return inner(justReturnArgs);
    }
    //</diagram#53>
}

And this is how we execute it:

var arr = new[] { "A", "B", "C" };
var stringBuilder = arr.RightFold(new StringBuilder(), (sb, curr) => sb.Append(curr));
stringBuilder.ToString();// returns "CBA"

This is a right fold of IEnumerable of T. Similat to Enumerable.Agregate but the folding is from right to left. And below is the diagram that sheds light on the execution process of this function. As you can see I try to use the same variable names to make it easier to apply the abstract visualization to the real code.

Inside the code I use comments with the ID of my diagram so I can always find it later for reference. In the diagram I will also write down the position in the code. I may use visual tools for drawing the diagram or just a sheet of paper and a pencil. For my visualizations I may use some traditional UML diagrams of just more creative approach as the one shown above.

The positive effect from this process is not only in the fact that I will have this diagram for future reference but also that I devote the time to reflect on the problem from a more visual angle and thus have another chance so spot an architectural flaws in my code. I will also keep all my diagrams as images inside my code to help other developers that may work on that code or to help me remember it if I have to revisit it back in the future.