videlalvaro

The other day I stumbled upon an open source project that had the following README.md, explaining how the project's source code must be read. I won't name the project, but I'll share the warning here, because I think it's a good guideline for when it comes to learn about the source code of a new project.

Thus, the reader can use the code as they see fit. As with any other program, some will look up a class or a method that interests them at the given moment, whereas others may look at the source code as a text meant to be read in its entirety, from beginning to end, in one sitting. so as to gain a complete picture of the project, the people, issues, and events connected with it. The project’s files can be read from top to bottom or from bottom to top. The three main modules of this project—Backend, Frontend, and CLI-utilities—can be read in any order the reader desires; they may start with the module that calls their attention as they browse files in their file manager of choice. That is probably why in the beginning these modules were published in three separate repos. The same has not been done here, for technical reasons. The source code of this project can also read diagonally, to get a cross-section of all three registers—the Backend, the Frontend, and the CLI. The best way to use this guideline is to work in threes by choosing three different classes connected by the same issue in the history of the project. This gives the reader an integral picture of the classes in the three different modules of this project, which tell of the participants in its development.

But the reader should not be discouraged by such detailed instructions. They can, with a clear conscience, skip all these introductory remarks and read the way they eat: they can use their right eye as a fork, their left as a knife, and toss the bones over their shoulder. That will do. They may, of course, wander off and get lost among the files of this project, as did Masudi, one of the writers of this program, who wandered into other people's bugs, never to find his way back. In that event, the reader has no other choice than to begin in the middle of any given file and forge their own path. Then they may move through the project as through a forest, from one marker to the next, orienting themselves by observing the stars, the moon, and the cross. Another time they will read it like the buzzard that flies only on Thursdays, and here again they can rearrange it in an infinite number of ways, like a Rubik cube. No chronology will be observed here, nor is one necessary. Hence, each reader will put together the project for themselves, as in a game of dominoes or cards, and, as with a mirror, they will get out of this dictionary as much as they puts into it, for, as is written on one of the files of this project, you cannot get more out of the truth than what you put into it. After all, this project's source code need never be read in its entirety; one can take half or only a part and stop there, as one often does with programs. The more one seeks the more one gets, and the lucky discoverer will ultimately have in their possession all the links connecting the classes in this project. The rest will be for others.

Perhaps I wrote it, or perhaps I adapted it from Dictionary of The Khazars