Excellent technical community will produce a lot of dry goods every day, “XX framework source code analysis” is one of them. However, this kind of article is often not popular, popularity is often inferior to “teach you XX”. Are we really too impetuous? This article hopes to look at this problem from another Angle.

From college textbooks to technical writing

Chinese university classrooms are known for being scripted, and university textbooks written by individual schools are notoriously dull. So, what does a bad textbook generally satisfy? Here are just a few:

  1. The subject matter is so complex that it’s hard to learn it without a textbook.
  2. The course content clearly has a better classic foreign textbooks, but they have to rewrite a set.
  3. Almost not talking about the meaning of each chapter, up is a long boring section of theorems, proof.
  4. With lots of exercises but no answers.
  5. Small publishing houses do not have any proofreading, there are all kinds of obvious mistakes.

Then let us contrast, an unpopular “XX framework source code analysis” and meet what conditions?

  1. The framework of the analysis itself is complex.
  2. This framework has been analyzed many times.
  3. This is just a bunch of code.
  4. Some key places have been skipped, paste the source code or do not understand.
  5. Typographic wording is confusing.

See? It’s a perfect match! If there is any difference between the two, it may be that bad textbooks are paid and bad articles are free.

Values of technical articles

Can write source code analysis of the article, most of the students are a lot of reliable dry goods, I am not to say that source code analysis of the article is garbage. Here, we might as well change the question to consider, namely why Chinese university textbooks are despised by people?

No contrast, no harm. Let’s take a look at the way undergraduate science and technology textbooks are written in the United States, where higher education is developed:

  1. Tell the reader what the class is about and what the problem is.
  2. Use paragraphs of text to show the reader how to break down the problem step by step.
  3. Give some formulas and derivations to explain how to solve the problem (in simple cases).

By comparing the compilation ideas of American imperial textbooks with those of The Chinese Dynasty, we can conclude the deviation in values between them:

  • Chinese: normative values that focus on the systematic and structured presentation of knowledge.
  • American emperor: reader-oriented values, focusing on how to make readers understand knowledge.

This is where the difference lies: many tech dry goods, like University textbooks in China, do not make communicating knowledge to the reader a priority, but instead spend a lot of time Posting codes that tell you “it’s complicated, I get it!” . However, even in silicon Valley whiteboard interviews, the code volume is not more than 50 lines, often dozens or hundreds of lines of the beautiful [full example] source code, can not read the reader really understand in just a few minutes reading time?

However, thanks to the commercial atmosphere of “praise first and then read”, most of the novice students who do not understand this kind of article dare not attribute the responsibility to the writing idea of the article, and will only feel inferior that their [level is not enough]. So, the new people in order to improve the level, also put into the army of source code reading, after difficulties finally got growth, write a pair of the same framework the same source code of the same analysis, want to slay the dragon warrior also finally became a dragon.

As a result, the problem with many technical articles that feel obscure may lie not in the technical content itself, but in a more basic way of writing. In addition to the source code parsing class article mentioned above, similar technical content includes:

  • Write Debug notes to yourself that contain a running list of business details.
  • Introduce a technology point to share PPT, come up to talk about a bunch of advanced features, for fear of others feel that the depth is not enough.
  • Description module interface documentation, do not tell their own features and overview, directly throw a [call example] to call the API all over.
  • …

However, as long as the value orientation of the writing is slightly changed and sorted out according to readers’ way of reading comprehension, they can easily become high-quality dry goods from which readers can learn knowledge:

  • It is a Case Study of great significance to sum up the running account by asking more Why. Peel off the business content among them, it is to save the later time to step on the pit guide.
  • Instead of sharing entire screens of code on a powerpoint presentation with intuitive graphics and raw pseudocode, it’s an illustrated guide to getting into a pit. (When Facebook talked about React, it had only a few lines of code.)
  • The internal technical documents dare not see light according to the features, examples, API process, is to achieve open source level of reliable documents.
  • …

Even simple changes in values can make a big difference. My personal example is: it is also a summary of the development of the simulator. When I first wrote the implementation of the Chip8 assembly simulator, the theme was “I am good at this stuff”. After a period of growth, the improved how to implement a microcomputer simulator with less than 3KB JavaScript is a tutorial designed to share and hopefully make newcomers understand. Please compare them with each other so that you can evaluate the readability of the article.

The pattern and significance of source code analysis

What is introduced above is the concept of transforming value orientation. For many technical articles, clarity can greatly improve the reading experience, but for articles on source code parsing classes, I have a bold idea that they may not be as difficult to write as the title suggests, nor of practical use to novice readers.

Here I propose an algorithm that can easily do source analysis for any framework:

  1. Frameworks encapsulate the underlying complex API and find a place in the source code to call it in. Search any place like this. It’s everywhere.
  2. Let me add a line herethrowAn exception, run the framework to make it report an error.
  3. Find all the functions in the error stack, copy them in reverse order into your XX source code analysis, and translate the comments into Chinese.

Three steps! While this algorithm is ridiculous and boring, I’ve actually seen some articles written as if they were stacked in this way. The art of code is to simplify complexity, but this content is to simplify complexity, and it’s normal to feel uncomfortable reading it.

In addition, due to the nature of code, the best code readers may not be apps from the technical community, but powerful ides. Can source analysis articles be used for breakpoint debugging, mock testing, and runtime variable content? Having the source code is enough in itself.

This has the awkward consequence that when we want to know the implementation details of the code, the first choice is often not someone else’s source code analysis article. For example, when I was writing the Chip-8 simulator, I found that one of the instructions in the language documentation was vague. At this time, I first thought to refer to the previous implementation of the Java version of the project source, rather than looking for a “simulator source code analysis” to read. Since the Source code itself is already Single Source of Truth in most cases, will second-hand materials still be a high priority?

But isn’t the parsing of source code useless? This is even more wrong. The ability to read source code is definitely the development of students’ hard skills, so in what occasions will use the source code analysis? There’s one situation I’ve found it to be useful in: writing a description of a Pull Request.

When we present PR to the community, we usually explain the trilogy of “what problem to solve, what code caused the problem, and what the solution is”, and the readers are already the maintainers of the background knowledge, so this information is very helpful for PR discussion and integration.

Think back, Chinese university textbooks are not all bad, right? They come in handy when reviewing for exams. The source code parsing class article is like an outline that needs to be given to someone who has already read it once to get the most out of it.

conclusion

Since there seems to be a lot of criticism above, it is worth clarifying the main theme of this article at the end:

  • Far from being too dry, many technical articles are so dry that they become tedious to read.
  • Simple changes in the way you write can greatly improve the reading experience.
  • The content of the source code analysis class is better described as a discussion of a Pull Request than as a way for newcomers to understand the framework.

Finally, for possible doubts, the author’s personal Github has many slot point high toy source code, please do not hesitate to ridicule 😅…