Flow diagrams

Taking the habit of documenting your application’s flow control with proper diagrams will allow new-comers to your code find their way through the code base much faster. Let’s take an extremely simplified flow diagram of the template’s main app, which loops over an index n and compute the fibonacci value for that index.

digraph sm {
    size = "5,8"
    overlap = False
    pad = 1

    node [ shape = rectangle ]
    start [ label = "start" ]
    exit [ label = "exit" ]

    node [ shape = circle ]
    main [ label = "main()" ]
    init [ label = "n = 0" ]
    increment [ label = "n += 1" ]
    { rank = same; increment }
    fib [ label = "fibonacci(n)" ]


    start -> main
    main -> init [ label="init" ]
    init -> fib
    increment -> fib
    fib -> increment [ label = "n < 10" ]
    fib -> exit [ label = "n == 10" ]

    {
    rank = same;
    fib -> increment [ style=invis ];
    rankdir = LR;
    }
}

Example of a state machine

This graph is built automatically during the documentation generation using an external dependency called graphviz. The graph image is generated based on a graph description which defined in a separated text file.

The beauty of it, is that you can maintain the graphs as easily as you maintain your code, without the need for any external tools. And the same holds true for automatically generated documentation (see Documenting your project with Sphinx and reStructuredText)

digraph sm {
    size = "5,8"
    overlap = False
    pad = 1

    node [ shape = rectangle ]
    start [ label = "start" ]
    exit [ label = "exit" ]

    node [ shape = circle ]
    main [ label = "main()" ]
    init [ label = "n = 0" ]
    increment [ label = "n += 1" ]
    { rank = same; increment }
    fib [ label = "fibonacci(n)" ]


    start -> main
    main -> init [ label="init" ]
    init -> fib
    increment -> fib
    fib -> increment [ label = "n < 10" ]
    fib -> exit [ label = "n == 10" ]

    {
    rank = same;
    fib -> increment [ style=invis ];
    rankdir = LR;
    }
}