With the recent shift toward AI-assisted programming, the readability of code
has become even more important. AI agents can read and modify code much faster
than humans, but they are not as good at understanding the intent of the code.
Adding human reviewers to the process can help, but given the volume of code
being written, it is crucial to have code that is easy to read and understand.
I'm working on a project that aims to improve the readability of TypeScript
code. These are some of the problems that I have identified as making code less
readable.
Modern IDEs have a lot of features that are controlled from the IDE window.
These controls occupy a lot of screen space, leaving less space for the code
itself.
This becomes worse when the IDE is used on a laptop or when source code control
operations are performed, such as viewing diffs or resolving merge conflicts.
A typical IDE window now has a file tree, a code editor, and an AI agent or chat
panel. Additional tasks such as viewing diffs or resolving merge conflicts can
result in the code editor being split into multiple panes, leaving very little
space for the code itself.
When code is modified, the diff shows all the changes made to the code. However,
sometimes the changes are not directly related to the change being made, but are
triggered by formatting rules.
A method rename can change the line length, triggering formatting rules that
alter code unrelated to the change being made. This can even change the
indentation of large code blocks, making it difficult to understand the actual
change being made.
An important factor in readability is code density. Long lines with many
statements and expressions are hard to read.
When code is not spaced properly, it becomes difficult to identify control
structures and understand the flow of the code.
Developers writing or modifying code for others to read are generally willing
to follow formatting rules. However, when the rules are too complex, they can
be difficult to follow, resulting in inconsistent formatting, frustration, and
lost productivity.
When code structures are formatted in different styles, it becomes difficult to
identify control structures and understand the flow of the code.
This can be caused either by a lack of formatting rules or by rules that are not
deterministic (i.e., the same code structure can be formatted in different
ways).
There are common solutions and mitigation actions that can be taken to address
these problems:
I've started with the first step, which is to design a set of formatting rules
for TypeScript and implement them in a code formatter: sfmt. I'm building it by studying popular formatting tools and linters for TypeScript
and adding custom rules on top of them. Some of the tools that I have learned
from are:
If you are interested in this project, please check it out and provide feedback
or subscribe for updates. If you prefer to follow along and want to support the
project, I would appreciate a star on GitHub.