There is a technique called literate programming, in which explanatory text for a program is mixed in with the source code. We can generate explanatory articles from the source code.
Literate programming is a programming paradigm introduced in 1984 by Donald Knuth in which a computer program is given as an explanation of how it works in a natural language, such as English, interspersed (embedded) with snippets of macros and traditional source code, from which compilable source code can be generated. The approach is used in scientific computing and in data science routinely for reproducible research and open access purposes. Literate programming tools are used by millions of programmers today.
Literate programming is a suitable method for writing source code explanations because it allows documentation to be managed in a strongly tied way with the source code. However, the generated commentary articles only follow the order in which the source code is written, not the order in which the programmer implements the code.
It is easier to understand source code explanations if they are given in the order in which the code was implemented since the explanations follow the programmer's thinking. The method proposed based on this idea is the literate commits.
The history of a commit becomes an explanatory article by describing the commit message with sentences that explain the contents of the commit. This method makes it possible to explain the commit in the order in which the code is modified, making the content easier to understand.
The disadvantage of this method is that we need to commit with a lot of care. It isn't straightforward to do commits while considering that the commit history will be used as an explanatory article.
Therefore, I would like to propose a method called literate diff. In literate diff, we retain the source codes as a snapshot for an explanation. In the article, we can place the link to these codes. When the article displays the link, the diff between the source code and the previous source code is displayed. Specifically, the article will look like the following.
Creating the One-Button Mini-Game PIN CLIMB
When you scroll down this page, you can see the source code fragment on the right side of the screen as a diff. The explanation on the left side of the screen corresponds to the fragment. Furthermore, you can see the screen that can be realized with the current source code in the lower right corner. In this way, you can see the process of completing the program while viewing the explanation, source code, and screen in parallel.
With this literate diff method, I think it is possible to create an article that explains how to create a program step by step, without much burden on the article's author.
The code to create an article using the literate diff method is in the following repository.
abagames
/
literate-diff-viewer
Show source code description with literate diff way
literate-diff-viewer (DEMO)
Show source code description with literate diff way. Literate diff is a source code description method influenced by Literate programming and Literate commits.
How to use literate-diff-viewer
- Use for multiple source code files on your web server.
- Use for a committed source code file on GitHub.
Reference
type SrcType = "show" | "hide" | "silent";
type SourceChangeEvent = {
oldFileName: string;
currentFileName: string;
type: SrcType;
};
type Options = {
readmeFileName?: string; // default: "./README.md"
srcDirectoryName?: string; // default: "./src/"
isFetchingFromOtherHost?: boolean; // default: false
onSourceChange?: (event: SourceChangeEvent) => void;
postProcessSource?: (src: string) => string;
storageKeyName?: string;
};
type SourceFileNameElement = {
element: HTMLElement;
fileName: string;
srcText: string;
type: …
Top comments (0)