While looking for a way to produce ASCII art of diagrams I ran into this nice story of why visualizations of code can give a fundamental help to programming (my highlights).
“If I can’t draw it, it’s probably because I don’t fully understand it”.
What prompted this article was one of those fortunate moments when you call on a collegue to help you out in a given situation (as fraught with danger as asking a collegue for help is) and you actually learn something useful. In this case I was struggling to untangle some logic that relied on 3 or 4 relatively unrelated variables in order to implement some specific business rules for my current employer.
So I called in a collegue and asked him to let me explain the logic to him so that he might help me untangle it. To assist me I drew a picture, and then another, and then another, before finally giving up and bringing up the relevant source code (what a cop out!). This at least allowed me to explain the complexity of the problem, and it was at that point that Ed (my collegue) said, “This needs a state diagram”.
To which I said, “Sounds good to me. Off you go then”. So as I explained, Ed drew the state diagram and within 10 minutes we had it all sorted out and found another logical bug to boot. Then I said, “That’s the fundamental problem with high level logic that relies for its input on the result of source code residing in a variety of different source files, its just about impossible to comment (or something equally succinct!).
“What would be great would be a way of putting diagrams like this in the code“. And then it all fell into place.