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