How do you visualize code?

I just don't visualize it much.

I do visualize dataflow, and tend to encapsulate responsibility boundaries, so as to be able to assert properties of a bunch of code and not have to think about the internals. But other than big block analysis I just don't break it down that much.

I've been coding for 37 years, 23 of those professionally (it's not bragging, just to establish that I've read and written a lot of code), at this point I just kind of read the code a bit like prose, or more like a "Choose your own adventure" book.

I do like to have the ability to navigate symbols and do typed searches of a code base, I also appreciate typing and mutability properties of things (everything is assumed mutable unless proven otherwise, which complicates concurrency analysis).

It's my experience that most coders think similarly, and you can usually assume quite a bit about how something is structured once you grasp the style of the programmers that built it, this also means that sometimes you can even predict the kinds of bugs they will tend to have. We're not all so unique after all.

In 'Why we talk' (https://www.amazon.com/Why-We-Talk-Evolutionary-Evolution/dp...) Dessalles arguments that we have two modes of talking - the first one is visual and probabilistic, the second one is topological - that is concerned about zero one questions - like if something is inside or outside of something. The first one is about imagining situations and judging their salience (or improbability). The second is about argumenting - simplifying the information so that you can 'proove' stuff. The point is that visuals are too rich and there can be too many ways to imagine things - so it is hard to convince someone that a particular scene is wrong or right. When you simplify things to the topological level of question if something is inside something or outside - then you can use inference to arrive at some logical conclusions, with steps so obvious that it is hard to argument against them.

Programming is mostly about logic - that is why it is hard to visualise. I think this is the problem with 'visual programming languages' (like https://enso.org/ - which, disclosure, is in my investmet porfolio) - and also here. This is kind of surprising - because we naturally expect the visuals to be as rich as the logic. But we need to carefully think about what is complementary here.

I find that programming languages are themselves a great reference... for the logic of a single thread. The moment you start doing concurrent development, or hell, even basic event-driven code, it gets much harder to "just read along". This is where I would kill for visualizations to help out.

Like, if you fork your process at a point, vertically split the text into two columns with a line saying "new thread over here". And then highlight any points of synchronization.

I think when people think of visualizations, it's "everything is a 2D graphic". When really, there could be new ways to laying out and navigating text-based source.

Aphantasia. I don't do "visual"

I have an odd form though, I do maps of relationships - including obligations and expected deliveries. Works largely for people and places too. And yeah, including likelihoods of delivery or accuracy of result.

So I have a default rule of "always check inputs". One can always take a section of the map and - like algebra - substitute a variable for a block, and keep that separate to keep problems more manageable.

When I'm reading code, I'm building a map in my head of how it does things.

I'm not very effective at communicating such maps, so I have difficulty writing or speaking some of the time, but it's no barrier with programming.

I know it's filesystems and not code, but the SGI Irix "fsn" file system navigator, featured in Jurassic Park, seems worth mentioning:

https://en.wikipedia.org/wiki/Fsn_(file_manager)

As a fractal mental miasma of equations. Doesn't everyone?

https://www.youtube.com/watch?v=GIKfEAF2Yhw&t=30s

I still support a full stack web app that I wrote for a client 10 years ago.

Whenever I revisit a section of code that I haven't looked at since then, I always have to re-learn the code's logical structure and function. I'm sure most developers have experienced this.

I wonder if, 10 years ago, I were to have routinely viewed my code in a visual manner like in the article, would today's relearning process take less time and frustration.

Sort of like when you revisit an old beloved vacation spot. Even though those memories have aged, the layout of the spot is relatively the same. You quickly remember where things are located.

I also wonder what value a code visualization like this would have for a new developer working with the code.

In couple of my previous jobs I often needed to quickly understand large, disparate codebases, without having them compile.

I've used Source Insight (https://www.sourceinsight.com/) to do this with great success. SI builds the typical tree of nodes and dependencies, except it can do so without having to compile anything, and can do so with multiple languages. It also has absolutely superb code/fuzzy search experience.

Really old school tool, for a while it was site licensed at Microsoft, ran by just a few devs here in Issaquah, WA.

The challenge of becoming a programmer is that of learning to flip between all these different mental visualizations and more, unconsciously and without effort, just as the challenge of becoming a musician is that of seeing melody, harmony, intonation, progression, rhythm, phrasing, dynamics, and so on, without effort, as each moment demands.

For TypeScript I created a visualization of function calls - a function call graph:

https://github.com/whyboris/TypeScript-Call-Graph

I have been intrigued by the idea of visual coding tools for many years, but these kind of tools have always disappointed me. They remind me of the system used to teach small children to program in the programming language Scratch, see [Scratch].

I prefer to "visualize" my code as manipulating a set of logical assertions that characterize the state of the computation, ultimately reaching the point where the state of the computation's properties satisfy the requirements. Somewhat like that explained in [Gries1987] and [Dijkstra1976]. Visual tools are just too coarse to capture the details necessary to ensure correctness or real-life requirements.

While UML diagrams sometimes help to make sense of a complex set of OO Class relationships, this is far from how I normally work with the meaning of code in my head while programming.

[Scratch] https://en.wikipedia.org/wiki/Scratch_(programming_language)

[Gries1987] https://www.amazon.com/Science-Programming-Monographs-Comput...

[Dijkstra1976] https://www.amazon.com/Discipline-Programming-Edsger-W-Dijks...

Code Bubbles (from 2010) is the most convincing code visualization tool that I can recall: https://www.youtube.com/watch?v=PsPX0nElJ0k

Shame it never grew beyond a research prototype.

Slightly tangential: This is how I visualise how the behaviour of the QR algorithm varies over all possible PSD matrices: https://en.wikipedia.org/wiki/QR_algorithm#Visualization

In this case, it's less important to understand the convoluted structure of some code, than to understand how a simple but opaque algorithm behaves in general.

For me, Pascal is a pretty good 2d map as software experience. Begin/End pairs along with indenting 2 spaces each time make it easy to understand and provide landmarks that are easy to spot. I imagine this is true for most languages.

The only thing better would be if I could compile it to an abstract syntax tree I could manipulate, change the name of a routine, etc... then reverse back to updated code.

AppMap (https://appland.com/docs/how-to-use-appmap-diagrams.html) is an open source tool we created to record and visualize code execution. It currently includes interactive dependency graph and trace views, and works with Node.JS (+TypeScript), Ruby, Java, and Python.

I found it odd that the drawing were confusing until I added my own personal imaginary time component.

Spacial memory include how I "feel" about something as much as the logic of what it is. When I misplace something I "feel" like I put that object (keys, book, etc...) in some place, despite it not being there.

So, like the idea of "I remember putting my keys here", there is a timeline.

The images of the boxes "main" and "counter" with all the lines was confusing, but if I had drawn them myself, I would have tiny timeline/memory of each line movement from one to another. Just the same as I recall (vaguely sometimes) why I wrote a piece of code or structured my files some way.

So, to change the thought from "what a mess of lines between the boxes" to "these lines really mean something to me", I would either have to have drawn them myself, or have some time component (ie, lines drawn during actual demo of code being run) to represent "how I visualize" the actual logic/code/system.

With Darklang we're trying to break up the "file" concept of code and organize the code as you think about the architecture (think about the diagram you would draw if you were to whiteboard the architecture to a new coder on your project).

The first version of it isn't great, but it is a bit different than the default:

https://twitter.com/tarngerine/status/1254276194402545664 https://twitter.com/_paulshen/status/1321511924807331841

Here's what we actually want it to be like though: https://twitter.com/paulbiggar/status/1322221106779049984

One of my professors in grad school was really into code visualization and we dabbled through a survey of the code viz approaches back then (~10 years ago now, geez).

I do not visualize code. I did, once, in a way, but that faded...

Any serious attempt to view code in a true multimodule/multithread/dynamic/static way to really _see_ the whole thing in toto takes us out of the Euclidian space we all wander in, to the _different_, tree based, non-linear space of a turing machine simulating some aspect of an extended lambda calculus (how extended? depends on your language). Code flows into and out of data, closing, suspending, and continuing, on one or more processors on one or more computers, through dizzying heights of dependencies, libraries, networks, and languages.

A Riemannian/Euclidian space is simply not the model needed to break into actual code viz.

I think it's madness that we don't work like this. We would greatly increase productivity. Unfortunately, like most new ideas, few people see the potential.

In a real world program, the number of branches is too high to be nicely represented in 3 dimensions: take whatever visualization approach you like (UML, drakon, visual flow, ...) and imagine how it scale to just a modest programs.

I guess the constructs of the programing language has to be designed to produce a visual representation: a strict hierarchy must be imposed to hide complexity.

At the end of the day, the question is: why using visualization? - if this is to use visual memory, can one trick the brain with colors, fonts and background images? - if this is to have 10,000 feet pictures, can statistics answer your questions?

I’m not a professional software dev so apply many grains of salt.

I code with pen and paper beside me, specially when doing anything that involves another thread or these days a go-routine.

Drawing boxes and lines to symbolise go-routines and channels.

The hardest thing for me about software is understanding a large code base. Often I struggle to even understand where the “entry point” is, let alone the whole thing.

A viz tool that would sequentially build a function/module/file call walkthrough the code would be awesome. Bonus points if it can limit the depth so dependencies are not traversed etc

Edit: posted too soon by accident.

No love for UML ? https://www.omg.org/spec/UML/2.5.1/About-UML/

For run-time visualization, I use Chrome about://tracing it gives very good details, over a time horizon, synchronized over multilple threads/processes. Zoom into nanosecond detail or zoom out over seconds or minutes overview.

I have my own simple C++ code to generate those traces (json data), there is also an official sdk for it (Perfetto is the new shiny way)

For static code analysis, I use Doxygen, it parses the headers, can make high level module diagrams and fine grained dependency graphs. It uses Graphviz/dot for rendering the graphs.

I think of code as a series of nerve cells. Nerve cells have internal logic (the nucleus) and a connection to others (the axon). Nerve cells should all generally be about the same size; one being bloated is a sign of a code smell - an area that could be refactored into smaller chunks. Real nerve cells only have one axon but, in programming, a single connection to the rest of the code base just isn't always realistic. However, a spaghetti mess of interconnection within a codebase is a code smell too.

When I have trouble juggling a complicated system in my head, I like to visualize it as documentation.

Thanks to automated documentation generators it’s possible to document various units directly in the code, but it doesn’t replace tying it all together in a cohesive knowledge base, nicely formatted in HTML. (There’s tooling that helps with that, too.)

To me, writing and updating how-tos, references, glossaries, organizing it in sections is a methodical activity that produces useful questions and helps me understand not just the responsibilities of different units do but also general background and the larger picture, while producing a concrete deliverable useful to future maintainers and operators as a side effect.

Illustrations can also be useful to include. There isn’t a one-size-fits-all approach and it really depends on what you are trying to illustrate—a high-level architectural overview may warrant a data flow or component dependency diagram, while a complicated communication between threads might call for a timeline view. (Again, thinking in terms of documentation is useful—consider future readers and future maintainers, what they would want to learn and how much of a pain would it be for them to update.)

I believe illustrations don’t work as well on lower levels though like individual code units. If a higher level diagram is not enough and you come up with one that has to change every time implementation changes, perhaps somewhere there’s coupling that could be loosened and cohesion that could be tightened. (That, or I might not have worked on sufficiently complex projects.)

his example is literally just data flow programming: https://www.youtube.com/watch?v=WjJdaDXN5Vs&t=924s

I've had a project related to this on the back burner for a little bit - data flow programming is really cool and helps with understanding code logic (and can be inherently reactive, which is IMO the future of programming) but it's hard to scale up.

> This made me think about how I tend to visualize code, and it’s a little hard to describe.

This tells me someone is good at imagining castles in the air and that they have difficulty describing their vision. I can't even tell if the castle is stable, shimmering, changing color or shape.

There is an analogy to at least some forms of meditation here: the vision is a distraction to suffer through (however pleasant the suffering) to return to the practice.

I recommend working on the problem and being able to articulate and understand the problem. Two people could see and enumerate a castle and a bridge (and little else) and agree on this vision. Then one could propose burning it down, while the other would propose a trebuchet or breaching mine. A breaching mine would be overkill for a castle made of wood, but stone don't burn. We don't even know if the bridge goes over the walls or even touches them.

I love interesting and entertaining mythologies and applaud them, but they're not to be conflated with The Problem. Listen carefully to the mythologies of the people you work with, and watch carefully if they're more interested in spinning a tale or working on the problem.

Calling code on the left, function-being-called (or rather, its stack frame) on the right. Unless it's asynchronous message-passing stuff in which case the parts are in disconnected spaces.

At my previous job there was a lot of code that abused a pub-sub system to effectively do buggy temporally-coupled RPC. This didn't fit any paradigm I knew how to visualize (it went straight into the "fucking mess, don't try to understand it unless you're going to fix it" section of my mental library) and therefore I had a very hard time understanding what was going on, or getting much done at all, for that matter. I opened some tickets with suggestions for ways we could make it make sense but management deemed that type of work lower priority than chair-warming (this was last fall during the 'employees should be in the office X hours per week' period; meanwhile I was living 300 miles away) so I gtfo.

Love this question and Im forever inspired by the way engineers visualize their code especially when actually white-boarding (in the before time...). Was hoping to see more actual visualization examples in the article / thread.

If anyone knows of a site or project dedicated to cataloging whiteboard visualizations point me in the right direction.

There's also all kinds of probabilistic visualizations, which is maybe a third axis in that diagram. (I.e. call coverage, sampling profilers, various o11y approaches)

Research example: http://www.ijstr.org/final-print/apr2020/A-Hybrid-Weighted-P...

I think that will be an important field especially for software running at a large scale - because it allows to get a better understanding of large systems. It's also a loss of fidelity that has strong implications for individual interactions.

(And yes, I know o11y is already a large tool there. I'm just thinking we've merely scratched the surface of probabilistic views)

I don't use visualisation tools but I sometimes need to write in plain English the code's intention.

When my brain is in a feedback loop from the complexity, writing simple descriptions can bring calm and help me grasp the required logic. It's usually a last resort.

I'm making a web game currently, as a side project for work. The complexity has snowballed because of all the timers, sequences and rapidly changing conditions. Honestly, visualization tools would get in the way and just add more complexity. Something else to maintain and update, no thanks!

It's a personal thing, but something about boxes joined to other boxes with lines, is very much not how I see code or programming logic at all. I leave that to managers who use those tricks to show other managers how the tech stack is organised.

You can visualize the actual execution of software at a very low level using the "graph views" built into "binary code analysis tools" (decompilers/disassemblers) like IDA Pro, Ghidra, and Radare2. Many of these tools can generate absolutely HUGE graphs showing the control flow of raw assembly, though they're frequently so large that they're more overwhelming than helpful. Hence why most of the time they are used to generate graphs of small and complex sub-sections of software.

Here are some example images showing control-flow graphs by different disassemblers/binary code analysis tools:

[0] Ghidra control flow graph, relatively zoomed in: https://i.stack.imgur.com/eYEVh.png Taken from this stackoverflow: https://reverseengineering.stackexchange.com/a/20792

[1] Radare2 showing control flow graphs in ascii in the terminal: https://monosource.gitbooks.io/radare2-explorations/content/...

[2] IDA Pro control flow graph, relatively large and zoomed out: https://i.stack.imgur.com/cjZBP.png From this stackexchange: https://reverseengineering.stackexchange.com/q/15847

[3] Defcon talk by Chris Domas where they demonstrated automate code generation which would cause various binary code analysis tools to generate control-flow graphs which formed specific shapes, shapes meant to offend or demoralize researchers examining the code (quite entertaining): https://www.youtube.com/watch?v=HlUe0TUHOIc

I don’t visualize code, I feel it, underneath my finger tips. I’m what they call a vimmer. Right now, when I think of a location in a code base where I want to go, I can feel the nerves in my hand anticipating the movements and keystrokes I’ll need to execute in order to get there, and the subsequent commands needed to make the edits I want. There’s little reason to look at the screen if all these moves are done perfectly, the screen is only there to provide context. The physical structure and layout of a project is irrelevant when you have powerful tools. It might as well be a flat file in my mind. All that matters is the anchor points. The words to search for, the phrases to find. This is the highest level of coding.

Here is my dumb army guy approach to programming anything. It doesn't work for everybody.

1. Think about the problem.

2. Form a tentative plan (the visual part).

3. Write a rough draft of code (the code doesn't have to work yet).

4. Test it and make it work (minimum viable effort).

5. Refactor. Polish the code and eliminate tech debt.

Think about the problem. Get a solid vision for what you want done. Once you have solid emotional confidence about that end state balance it against what you have. With that you know what you are missing. That stuff that is missing is the work you must perform.

When you think functionally everything is an input and an output depending upon context. This allows thinking about the flow control directly without worry for the composition. If you have been programming for more than a couple of days the leet code of loops and conditions are completely ignored from planning as implied tasks much like you don't spend your time actively thinking about breathing when planning your day. Now you have a plan. Plans often fail as soon they become necessary, so the plan itself is irrelevant. What's important is the planning, the thought exercise not the product, the thinking about what needs to be done so you know what to do.

Programming then becomes a conceptually visual experience. Simply the write the code you see in your mind. The most important thing here is that you have a visualized a plan and know what you need to write. The code doesn't even have to work at this point.

Then write the code. Test what you have written. Fix the code so that it solves the desired problem. Only then should you actively toil with composition. When composition is saved for last it becomes an exercise in refactoring.

Refactoring is a form of code polish. It allows cleaning away the rough spots from the rough draft in order to achieve conformance to code style, build rules, and validation criteria. Refactoring also allows the combining of similar mechanisms which increases simplicity and reduces tech debt.

Sorry, I don't have time to example all pros and cons but: - UML is complicated and nobody really knows that and it's sad; - Simple tool like Miro, Dia is the easiest way but you have to keep it updating manually; - PlantUML was fine. We used it on a PHP project but it was once and many years ago; - DOT language can be a mediator between code and visualization (graphviz) but nobody really develops it. I didn't find a library to parse it and language is full of problems like mixing visualization with representation, decomposition and etc. Huge potential but right now even XML is better.

A long time ago I was thinking about this and how if you could better visualise the relationships between functions/modules, it would be clearer to see where there are issues with coupling and cohesion. I think for the most part it could look fairly clean with nice heirarchical relationships, but then the links to common utility files could get a bit messy.

I took a stab at implementing it in Love2d but didn't get far before getting distracted with UI design/development: https://i.imgur.com/kznL4.jpg

Ever since I saw the cover of Elements of ML Programming [1], which shows the book as charting a course across "Logos Island", I've wondered what a programming language might look like as a navigable space. Perhaps something like walking through a syntax diagram, but that hardly captures it, especially when so much of the semantics of a language is in its standard libraries. Would a program be a path through the language world? Would we think of the world as containing all possible user-defined functions, and we'd edit our way across this space?

For a historical metaphorical discussion of visualizing programming, I enjoy this bit from Johan Georg Raeder's 1984 thesis "Programming in Pictures" pp79-80 [2]:

"What real-world metaphors can fit programming? To get a feeling for how immense our initial search space is, let us amuse ourselves with a few possibilities. Is a program like a road with intersections and forks where we have to make decisions depending on our current errand, and with roadside inns where we can spend computation time or, if we are careless, completely overflow our stack? Or shall we abolish the 'meta-view' and, instead of seeing the program from the sky, put the programmer inside the program by presenting a view of a tunnel he/she can drive through? At each intersection one might have to throw dice or make guesses to introduce some of the challenge, fantasy and curiosity found in computer games. Perhaps we should rather present programs as physical, three-dimensional objects that we can turn around and view from different angles and in different light so as to reveal the various facets of their structure. Can we present a program as a play with actors and objects on a stage?"

See also Raeder's "Survey of Current Graphical Programming Techniques" (1985)

[1] https://archive.org/details/elementsofmlprog0000ullm

[2] https://archive.org/details/RaederProgrammingInPictures/page...

Whenever someone presents a flow diagram to describe software or infrastructure, I pretty much panic. It always seems like everyone in the room immediately understands this kind of thing, but to me every box and line and arrow looks like sheer ambiguity.

I tend to think in bulleted lists. Programs are a series of steps, often containing substeps and branches. Infrastructure allows data (requests) to traverse a series of steps as well. Each branch of steps and substeps looks like a bulleted list in my head.

From a previous posting here in HN code2flow

https://github.com/scottrogowski/code2flow

https://news.ycombinator.com/item?id=29496014

A friend of mine sent me this a while back which is kinda related

https://splootcode.io/

Seeing code visualized was really helpful when I first learning programming. My teachers would draw block diagrams of variables/functions on the "stack" and the "heap". Helped me create a mental picture of what the code I was wrote was doing under the hood.

I created http://memlayout.com, which tries to accomplish this.

Curious about what people think about it.

Profiler flamegraphs can be a wonderful tool for understanding actual execution. It turns out that execution time is a useful proxy / reasonable approximation for code's importance to the overall application.

Bonus points for using an intrusive, explicitly annotated tracing API of some sort, which lets you capture enough parameter information to understand not just where, but what, the code is doing.

I'm trying to build a tool just for that. On-demand code visualization: https://sourcespy.com

I don't really visualize 'code' so much as I visualize data structures as arrangements of rectangular blocks of memory and arrows pointing to them. I find that once I understand how the data is supposed to move and transform, the code almost seems to write itself.

I am working on a technology illustrated design system book that might help you visualize code. I am a visual designer that learned to code. Its a free ebook on Apple - https://mtrees.io

does anyone here write code, align with having aphantasia, and have some form of an alternative answer to thread? alt.answer might end up being the same answers, idk what i'm saying, barely know what i'm asking

Giant mechanical machines with cogs and conveyer belts, shunting items around.

I draw graphs of it very akin to the schemas in the article

As a series of plumbing pipes.

Everything is a tree.