You have a task that requires using a certain open source project; or your boss assigns you a task to understand something. How to start? How to begin? Here’s my habit:
-
First, search for and read blogs and materials about the project. Through Google, you can find blogs that provide a general introduction to the project. A quick read will give you a general understanding of the project’s purpose, functions, and basic usage.
-
Read the project’s documentation, focusing on documents like Getting Started and Examples, to learn how to download, install, and even basic usage of the project.
-
If the project provides ready-made example projects, first try to run the example according to the introduction in the getting started document. If it runs smoothly, congratulations on a good start; if you encounter problems, first try to find answers in the project’s FAQ and other documents. Then, you can search for the problem (such as error messages) as keywords to find related solutions. If you encountered it, others likely did too, and enthusiastic friends will record the solution process. Finally, you can submit the problem to the project’s mailing list and ask everyone to help you look at it. Do not try to modify the example until you have successfully run it.
-
After running the first example, try to modify the example according to your understanding and needs, and test advanced features.
-
After understanding the basic usage, you need to start a deeper understanding of the project. For example, project configuration management, advanced features, and best practices. Usually, a well-run project will provide a user guide from shallow to deep. You don’t need to read this guide from beginning to end. Based on time and interest, especially the needs of your own task, focus on reading some chapters and take notes (Evernote is recommended).
-
If time permits, try to build the project from source code. Usually, open source projects will provide a build guide that instructs you on how to set up an environment for development, debugging, and building. Try to build a version.
-
If time permits and you are interested, you can try to read the source code:
(1) Before reading the source code, check if the project provides architecture and design documents. Reading these documents can help you understand the general design and structure of the project, so you won’t be at a loss when reading the source code.
(2) Before reading the source code, make sure you can build and run the project to have an intuitive feeling.
(3) The first step in reading source code is to grasp the main trunk, trying to clarify the code call path for a normal run. This can be done by debugging to observe runtime variables and behaviors. Modifying the source code to add logs and prints can help you better understand the source code.
(4) Draw appropriate diagrams to help you understand the source code. After clarifying the main trunk, you can draw the entire process into a flow chart or standard UML diagram to help with memory and the next step of reading.
(5) Select interesting “branch” code to read. For example, if you are interested in network communication, read the network layer code, delve into implementation details such as what libraries it uses, what design patterns it adopts, and why it does so. If possible, debug the detailed code.
(6) When reading source code, pay attention to unit tests. Try to run unit tests. Basically, a good unit test will describe the functionality and boundaries of the code clearly.
(7) After familiarizing yourself with the source code, if you find areas for improvement and have the energy and willingness, you can suggest improvements or issues to the project’s developers, or even help them fix and implement them, participating in the project’s development.
- Usually, after reading the documentation and source code, you can have a relatively deep understanding of the project. However, in the field where the project is located, you may also want to search for related projects and materials to see if there are other better projects or solutions. Balance between breadth and depth.
The above are some of my personal habits, and I don’t follow them completely myself, but following this order can basically allow you to learn and use an open source project more efficiently.
Reprinted with permission: Developer Relations »
