The Gift of Authorship is Gone

One of the greatest gifts in the craft of programming is "the person who wrote the code understands how it works."

As it relates to programming, the phrase "The Gift of Authorship" was coined by my friend Martin in conversation, but the idea is obvious. If you write a story, you know the story and the characters as well as anyone.

For programmers, this is a visceral experience. We know what it's like to get immersed in code and carry around an understanding of how a system works… because we held the spark of an idea for each new feature, carved it into existence, and debugged all the issues we didn't predict.

With the rise of AI code generation tools, the software development industry has been losing the benefits of this boon. But instead of lamenting it, I'd like to explore what the Gift of Authorship really is, and what we can do when we don't have it.

The Reality of "Understanding"

It's easy to say that the original author "understood the code," but as any programmer can explain, it's less like remembering a story and more like recalling the exact shape of the problem and details of the solution.

As a result, an author's understanding is not a monolith, but more of a collection of ideas and experiences spread between two primary pieces: 1) what the code is supposed to do, and 2) what the code actually does in its current state.

Both parts are important, but "what the code actually does" is more nuanced and more fragile. Naturally the details fade quickly, and the only way to maintain them is through constantly working on the code. Of course this isn't always possible in the real world, where there are typically multiple projects in play and multiple developers at work.

Even in the optimal case, any time a bug pops up, it reminds us that we as programmers always have an imperfect understanding of all possibilities. So every time any developer goes to fix a bug or work on code, they go back to the source to reconcile this new information and make sure they really understand what's going on.

The Cycle of Understanding

This process of (re)gaining a real understanding of how code works is commonly called "onboarding" and it is a point of friction in every developers' life.

The cost of this friction is time. It takes time to bring the concepts and realities of a codebase into our head, reading the code until we gain the level of understanding required.

This is common practice despite the obvious downsides:

1. Singular: each person who changes the code needs to understand the system, which is a per-individual process… unless another developer can help by sharing their understanding, at the cost of their time.

2. Unshared: A person's understanding cannot easily be shared, because any non-trivial system includes many concepts and detailed interactions (hence the dreaded "just go read the code").

3. Transient: The understanding a person has degrades over time as memory fades or as others change the code.

While this is an issue that LLMs can help with, even fans of the Socratic method will tell you that having code explained by walls of text is not the best experience. LLMs are typically weak at judging what is truly important, and as far as giving concise, insightful answers… Well, at least they produce shorter sentences upon request.

In practice, the presence of AI code assistants has the effect of removing the need for coders to get involved with trivial matters. While this saves time on trivia, the surprising result of using AI code generation is that programmers often need a more robust understanding when they get involved.

This is often because A) they didn't write the code themselves, or B) they are working on a task that a coding assistant needs help with: fixing a complex bug or rearchitecting part of a system.

But naturally the software developers have been dealing with code they didn't write for years, so what are some solutions, other than just spending more time reading code?

A Visual Approach: Code Visualization

Improving the code onboarding experience is one of the core problems we set out to address with VizDev. With years of experience in reading and reverse-engineering code, we've learned some key tools and strategies that make it faster and easier to get up to speed with code:

1. Show don't tell: If "a picture is worth a thousand words" then we should always start with visual explanations before zooming in on details

2. Interactivity: The ability to explore a diagram or change parameters increases the speed of insight

3. Automation: Exposing functionality with scripting or exposing it to/through an AI agent can unlock even more possibilities for versatility and speed

These aren't opinions as much as they are observations of what works for most people.

These are the principles that we built VizDev with, not just because we like visual experiences (we do!), but because they work.

The reality is that regardless of what your code-related task is, understanding code is required to make intelligent decisions, so reducing the time it takes to get there is huge.

While the Gift of Authorship is powerful, it has always been easily lost: the original author leaves the team, comments become out of date, even going on a long vacation can make our own code feel completely foreign to us.

Since this gift has always been fleeting, it's important to be prepared for its departure with tools and strategies for understanding code quickly.

This is one of the reasons we started building VizDev, so if you or your team want to understand code better than the person who wrote it, reach out to us today at info@vizdev.com.