AI Translated Document

This document was translated using an AI translation tool.
Due to the nature of AI translation, some sentences or terms may be interpreted differently from the original intent.
There may be mistranslations or inaccuracies, so please refer to the original text or consider additional review if accuracy is critical.
Your suggestion for a better translation would be highly appreciated.

Original Document in Korean

You Must Follow Intuition to Make Code Readable, and Readable Code Is Easier to Modify¶

HJ, Ph.D. / Software Architect
(js.seth.h@gmail.com)
Draft: January 2023 / Revised: December 2025

[Author’s Intent] This article does not take for granted the common belief that “readable code is always intuitive code.” Instead, it examines code readability not as a matter of personal feeling, but as an issue of communication style, shared literacy, and cognitive load.

Executive Summary¶

The correlation between readability and maintainability is often mentioned.
But there is little content that clearly defines readability.
It's just called intuitive code or easy-to-read code.
So what is readability? What does it mean to understand content easily?
Communication: Sender, Message, Channel, Receiver, Effect
Reception Theory
What is intuition?
Computer science is the shared literacy of developers
Cognitive load theory
If you stick to the basics, it's easier to find modification points.
Stick to collective intuition. To do so, see and learn a lot.

Readability and Maintainability¶

Readability and maintainability are concepts often mentioned together in software discussions. Usually, it's summarized as "code that's easy to read is easy to modify," but this doesn't sufficiently explain why. The mechanism is even less explained.

Maintenance is essentially continuous change. Change presupposes understanding the structure and intent of existing code. In this sense, readability is not an aesthetic or secondary quality, but a prerequisite for maintainability.

Code that can't be read can only be replaced entirely, not partially modified, because it can't be understood. So maintainability always requires both the developer's interpretive and writing skills. But just as most ordinary Koreans can't read Sanskrit, interpretive ability is tied to the text already written.

How Does Readability Work?¶

Readability—being easy to understand, intuitive—what process is this, specifically? We tend to interpret "easy to understand" as "it took little time" and "I understood it accurately." We often attribute this to "intuitive code." This is a valid observation, but much is omitted.

Let's start with "understand." It's abstract, but can be broken down into cognitive steps. When a developer reads code, the process is roughly as follows: First, grasp the structure: where code starts and ends, flow direction, boundaries of responsibility. Second, interpret the meaning: reconstruct the author's intent from variable names, function names, types, comments, etc. Third, predict the result: what the code does, what causal relationships exist.

Readability is not just about "understanding" but about being "easy" to understand. So we need to know what factors affect the difficulty of understanding.

Components of Communication¶

Writing is traditionally a form of communication. Code is a very detailed and specific set of instructions from a human to a computer. The computer reads and executes it, and colleagues or your future self read and modify it. So, to know what makes something "easy," we can borrow from humanity's knowledge of communication.

Communication theory mentions sender, message, channel, receiver, effect.

Sender: The person or group delivering information
Message: The content or information to be delivered
Channel: The medium or path for the message (e.g., speech, letter, code, radio, broadcast)
Receiver: The person or group receiving the message
Effect: The change or response in the receiver after the message is delivered

Here, we see that communication—transmission of content—is an interaction between speaker and listener, and even with the same sender, message, and channel, the effect differs by receiver. If you don't get this, just imagine the receiver as a developer or a computer. The computer will process the code as instructed, but a developer will not. We look at code for different reasons.

This develops into Reception Theory by British cultural theorist and media scholar Stuart Hall.

Reception Theory¶

Reception theory says the meaning of a text is not fixed at the time of writing, but completed in the reader's interpretation.

Stuart Hall argued that a media message is not simply delivered as the sender intended, but is interpreted by the receiver according to their cultural context and background.

Source code is no exception. Even with the same code, understanding varies by the reader's experience, knowledge, and context. So what's important is not the author's intent, but how consistently the receiver can interpret it the same way. In other words, "good readability = easy to understand" is not about individuality, uniqueness, or complexity, but about the stability/convergence of interpretation.

In practice, source code is not read by laypeople without programming knowledge, nor is it for a single individual. Source code is read and modified by a group of developers. So let's limit the standard of interpretive stability/convergence to developers with professional knowledge.

Is Intuition a Sense or Knowledge?¶

So, for the developer group, what determines the difficulty of reception?

Intuition is often mistaken for sensory judgment or personal ability, but it's actually the result of accumulated knowledge and experience. Many see strong intuition as "genetic," but intuition is a trainable trait through knowledge and experience (though the ease of acquisition may be genetic). To put it bluntly, it's a mostly correct bias/heuristic that skips intermediate steps.

So intuition is not a subjective sense, but knowledge reinforced by repetition, and not a random feeling, but the result of pattern recognition formed over many cases.

So, if we assume a group of developers with shared computer science expertise, intuition can be shared. If intuition were purely personal, you could write code that's intuitive to yourself, but not have a group agree it's intuitive. The fact that we can discuss whether code is intuitive proves we already share intuition, and that it's based on knowledge—specifically, socialized tacit knowledge.

For the exact concept of socialized tacit knowledge, see Japanese management scholar Ikujiro Nonaka's Knowledge-Creation Theory.

Computer Science == Developer Literacy¶

The source of our shared intuition is ultimately computer science knowledge established through university education.

The developer group's literacy is formed on the common knowledge of computer science. Data structures, algorithms, abstraction, modularity, understanding of state and flow—these are the common language of developers. Highly readable code actively uses this common language. Conversely, structures that ignore computer science context greatly increase the cost of understanding. So readability is not about kindness, but about adaptation to the level of computer science knowledge and development culture.

In fact, computer science concepts don't just exist abstractly in textbooks. In successful projects, appropriately chosen computer science concepts are fixed as structural choices, and these choices determine readability and understanding cost. Here are some examples:

Git log - DAG (Directed Acyclic Graph)
In Git, commits are not just logs, but immutable objects forming a DAG. Each commit references its parent, and branches/tags are just pointers to specific nodes. Merges create new commits, expanding the graph. Thanks to this, the complex problem of "history management" is reduced to graph traversal and pointer movement. If Git managed history as a simple sequential log or arbitrary script set, current understandability would be hard to achieve.
TCP protocol state - Finite State Machine
TCP connections are defined by states like LISTEN, SYN_SENT, ESTABLISHED, FIN_WAIT, and transitions between them. Each state explicitly limits possible/impossible actions. This structure simplifies the complex, error-prone problem of network communication stages into "a set of state transitions." Developers don't have to simulate all cases in their heads—just consider the current and next state. The complexity isn't removed, but the state model makes it manageable.
RESTful API - Resource Identifier
REST defines interfaces around resources, not just listing system actions. URIs like /users/{id} implicitly define what the resource is and its scope of responsibility. Limited verbs like GET, POST, PUT, DELETE standardize the types of actions on resources. In this model, API readability is determined more by clear boundaries than by documentation. In a well-defined resource system, you can predict the role and usage of a new endpoint without much explanation.

Literacy

Literacy traditionally meant the ability to read and write.
But today, it has expanded to mean the ability to understand and use information by applying specific knowledge or skills. It goes beyond language to include critical thinking and creative problem-solving in various contexts. For example, media literacy is the ability to analyze, interpret, and produce media content; information literacy is about evaluating and effectively using reliable information.

So literacy encompasses understanding, communication, adaptation, and application in a given subject, skill, or situation.

Cognitive Load Theory¶

But the fact that a group can share intuition doesn't explain differences in readability—i.e., differences in individual expression and reception.

Cognitive load theory starts from the premise that human working memory is very limited. There's a limit to how much information can be processed at once, and exceeding it sharply reduces understanding. There are two main types: intrinsic cognitive load and extraneous cognitive load.

"Cognitive Load Theory" was proposed by Australian educational psychologist John Sweller in 1988.

Originally, this theory was for learning, but reading code (your own or others') is also a kind of learning, so we can borrow it. Intrinsic cognitive load is the load from the inherent complexity of the code's function; extraneous cognitive load is the unnecessary load from how the code is expressed.

This cognitive load directly affects accuracy and time of understanding. So the main cause of readability difficulty is the total cognitive load between sender --code--> receiver.

And this total cognitive load—i.e., readability—can be improved. If the function is unique, there's little you can do about intrinsic load, but for common features like login, uniqueness is low. For extraneous load, since programming languages have limited keywords and well-known computer science expressions, it can be greatly reduced.

Differences in individual ability affect the appropriateness of metaphors, communication efficiency, and decision accuracy.
That's why teams of experienced members can achieve more with fewer people, and why there's a big difference between mid/high-level developers who can apply optimal computer science concepts and those who can't.

Intuition and Convention¶

Intuition and convention are often seen as unrelated or even opposites.
But they're very similar in that both are mostly correct biases/heuristics that skip intermediate steps. The difference is that intuition is tacit knowledge derived by the individual for the current situation, while convention is tacit knowledge derived by society for the average situation.

Convention is the result of collective experience condensed over time. Structures and expressions that survive repeated use tend to yield good results, so they become conventions. Once something becomes a convention, communication is easier, so it's used more, and more experience condenses, reinforcing it further. So conventions solve problems that converge to the average, and are average solutions. Thus, unique problems in different organizations can't always be solved by conventional solutions.

Intuition, on the other hand, operates entirely within the individual. While intuition can be shared through similar learning and experience, its exercise is personal, and it responds to the uniqueness of individual problems.

Because of this, the relationship between intuition and convention is tied to personal achievement.
Junior developers generally can't go beyond convention. But when personal experience and insight surpass the virtual average line of convention, convention can't keep up with intuition.

But since convention is the result of collective intelligence, it usually offers above-average solutions and the added benefit of communication efficiency. So in complex projects where it's hard to assimilate high literacy among all members, it's better to stick to conventions.

But this doesn't apply to simple imitation of convention. Since convention is tacit, simple imitation doesn't work well.

Maintainability and Literacy¶

Readability is often seen as abstract or vague, but a detailed analysis shows it's not.
If you stick to collective literacy, cognitive load drops, and individuals can exercise high-level intuition. That is, it's easier to quickly and accurately find the right modification point.

Differences in individual ability are practically constant in each case, so if you write design and code that stick to conventions—i.e., that make intuition easy—and use qualified people, you can lower maintenance costs.

Some say maintenance is a battle between your past and present self. This just means your past and present self didn't share literacy. For example, if you use a finite state machine (FSM) for some logic, there's a standard model, so the assumptions, logic, and conclusions are similar in decision-making. But if you don't use a computer science model to control complexity, you'll get different results and more conflict each time.

Simply put, the very question "Why did I do this?" arises because literacy wasn't shared between past and present, or predecessor and successor. If literacy is shared, you can avoid this.

Conclusion¶

Readability is not a sensory virtue, but a practical concept where communication, intuition, collective knowledge, cognition, socialization, and convention intersect.
It's not a vague or abstract term, but one whose mechanism can be explained.

The guideline "write as if it will be read" is valid, but omits too much.

Readable code is easy to understand and easy for others to modify.
The premise is a structure faithful to collective intuition and computer science knowledge—the literacy shared by skilled developers.

"Follow intuition" doesn't mean write as you feel. It means see more cases and internalize more knowledge.
"Follow convention" doesn't mean just imitate. It means internalize the collective tacit knowledge of the group.

If you use textbooks as pot stands, at least read them enough to explain to your juniors.

Author¶

HJ, Ph.D. / Software Architect
(js.seth.h@gmail.com)
https://js-seth-h.github.io/website/Biography/

Over 20 years in software development, focusing on design reasoning and system structure - as foundations for long-term productivity and structural clarity.

Researched semantic web and meta-browser architecture in graduate studies,
with an emphasis on structural separation between data and presentation.

Ph.D. in Software, Korea University
M.S. in Computer Science Education, Korea University
B.S. in Computer Science Education, Korea University