Binding Source Code Files Together Like A Book

A book unbound is hard to read. A folder full of code fragments is no different.

Today, when trying to practice writing human-readable code on my Tetris clone, I had the idea of adding a Table of Contents to the source code. It improved the readability of the codebase a lot, and the difference is like that between a loose collection of pages and a compiled book. Before now, I never thought about the organization of source code files as part of a software project. Since I use math to understand code, I never thought of text files as part of a book. I’m glad that I figured it out now, and I’m here to share my findings to you.

You may want to read the repository content (linked above) to understand how important the addition of Table of Content was.

Writing text-based software code is not that different from writing literature. Lessons from Publishing and Literature work well here. A POSIX file is like a page; unlike paper publishing, the size of pages varies in the digital realm. Although we can also use hyperlinks to directly link different documents together, the traditional Index Page format is still valuable. Line and grid patterns are more legible than solid color fill. Shape cues stand out way more than special type face. Paper or text editor, we are given a 2-euclidean rectangle to work with. I think software interface designers are too daring to try out different UI designs, yet don’t learn from history of publishing.

Here are some tips that may help other humans to read your code better. If you are trained in writing (literature), you should understand why quickly. Otherwise, you need to practice to understand how doing those helps readability.

• Add a table of contents in your code. Not in documentation. You are encouraged to solicit help from the type checker and LSP (jump to definition).
• If you can cut a word out, cut it out. (People give this advice often in programming too, but worded different.)
• Interleave functions of high and low obscurity (time it takes to read it).
• Order stuff by dependency. Introduce simple concepts first. (But do put the table of contents and prologue at the beginning.)

You can do any of theme to existing code. When cleaning up your code, compile (organize and label) it as well.

Now that I think about it, this website has terrible organization. I will clean it up soon. For the mean time, I wish you less pain when reading unfamiliar code.

In case you may ask, “But what about literate programming?” Here’s the anwser.

The concept never made sense to me. Duplicating information in programming language and natural langage made it harder for me to understand what I was reading.