What does a Rustc Reading Club do?

This is the question we are trying to answer with our pilot program to bring Code Reading Club techniques to understanding the rust compiler.

We started with experimentation in the exercises used to examine rustc source code. We continue to refine and adjust including introducing new tools to help us understand what the name resolver does and how it works.

In a Code Reading Club the goal is to get better at reading unfamiliar code, so a random section of code that is unknown to participants is presented. The code is read and participants record their observations after examining the code for some short period of time. Those observations are then shared with the group and discussed.

Rustc Reading Club differs from the original in that we are trying to understand a specific code base as opposed to getting proficient at reading various code bases. Our version of code reading benefits from the opening exercise of the Code Reading Club. We started by Niko choosing a crate for us to read through. Our goal differs from the Code Reading Club as it seeks to build code reading skill and we are trying to get better at reading rustc source code.

The first of Rustc Reading Club session focused on reading the rustc name resolver crate. The plan involved reading code at a broad level, then going deep into the code and finally zooming back out to the broad level.

Steps in the first session

1. Spend 10 minutes reading the code in the crate and note things we find interesting.
2. Share with the group how we approached reading the code and what we observed as interesting.
3. Focus on a single function and go deeper into the code.
4. Repeat the group discussion and questions that arose from reading the code.

What we found

1. So many interesting views of the code were generated from the first 2 steps that we didn’t need or have time for the zooming back out final step.
2. Different developers have different approaches to understanding the same code. Some focused on “the entry point” of functions and others focused on determining what was being returned. Some started by reading the comments or consulting the documentation.
3. One valuable observation was that we should include a link at the top of rustc modules to the documentation that describes them.
4. Trying to read a whole crate is too much for a single session and going forward we will work at the function level.

The next posts will describe how we further refined the flow of sessions and have added a debugging tool, so that we can observe the code in motion without needing to setup a rustc dev environment or try to run code in the short window of time available in a single session.

Stay tuned!