brian will . net

Everything said here.

I’ll just add that pictorial representation of code is fundamentally flawed because it inevitably means drawing a bunch of boxes and connective lines all over the place. Just as there’s no one true way to distribute your functions and classes in text, there is no true optimum 2D layout for boxes representing functions and classes. No algorithm does this layout well enough to not need human reworking. Every good diagram of any complexity you’ve ever seen, whether of code or of a subway system, has been heavily hand-massaged if not entirely hand-generated. Even if you had a decent algorithm for layout, the layout it computes might change radically each time you add a box or connection, which would be disorienting in the same way as if someone were to rearrange your workspace behind your back. A big part of what it means to be comfortable with a codebase is knowing where most things are. How familiar can you ever be if the codebase gets constantly scrambled? The only solution is to have the coder position all the boxes and draw the connections manually, but this will just mean that systems will get uglier and uglier as they grow and that refactoring the layout will grow more and more painful.

Text to some degree has these problems too, for you have to decide which file to put a function or class in, and you must then decide how to order the functions and classes of each file. But in text, you aren’t burdened with the stylistic choice of how to draw connections: everything has a proper name, and you make connections by using the proper name, end of story. Making connections pictorially is only simple if you stick to straight lines, which typically makes the diagram much harder to read than were the connections cleverly grouped and routed along the cardinal directions. Text code with many connections is complicated but readable; diagrammed code with many connections is complicated but totally unreadable. The whole point of diagramming code is to visualize connections, to see the shape of a design, but past a rather low level of complexity, the visualization is too much to mentally process.

In sum, stick to code for code. Use diagrams only for broad communication, and use them only when they are understood to be lies.