Reading Code and Mapping the Depths of a Project

Bringing a project to fruition can be a complex endeavor, rife with unforeseen surprises during development. In this talk from last month’s RubyConf India, Christophe Philemotte, founder of PullReview, an automated code reviewer for Ruby developers, explains what are some best practices for smoother project development.

Philemotte begins by explaining that when code is to be written, reading and understanding it is by far the most common development task. In reading over code, he notes that for every line of code that is written, one has to read it at least once. Philemotte estimates that, generally, 85 percent of development activity time is spent on reading. However, this percentage goes up to 90 percent for a new project, which means you have very little time to actually achieve something.

Diving Unknown Depths Of Project

Thus, Philemotte states that it is important to learn how to efficiently “deep dive” into a project to find what you need in order to achieve what you want to do, such as fixing a bug or styling the code. But it is imperative to know the destination or direction, otherwise it’s easy to get lost or have a problem. To counter any blind stabs in the dark, Philemotte explains “from the easiest dive to the deepest one, you need to prepare.”

Philemotte describes his approach to code development, where outlining a plan first can be of great assistance — where a goal is defined, and a “good map” of development is drawn, and using the right equipment is paramount as well. One cannot wander aimlessly, so a reasonable goal is the first thing that is needed to motivate and drive one to plan for a project — whether it be fixing a bug, implementing a new feature or writing documentation.

Philemotte further explains that to determine a direction, some “map” basics include knowing where the project stands, any introductory documentation, how to communicate with other members of the development team, or the location of the issue tracker. Philemotte cautions that while it’s great to have a map, one still needs to know how to use it, and for this, one needs “great legends.” If there are no good legends forthcoming, then look for the contributing guidelines where you can find all the necessary information on how to contribute to the project. Philemotte clarifies that a “domestic guideline” is the code of conduct that reminds you of the protocol of interaction with other developers and best practices on how to proceed during project development.

Philemotte adds that one needs to understand resources like directories and hierarchies, which is where one can find tests, documentation or even source code.

“But you don’t have to be exhaustive, you just have to find what you need,” says Philemotte.

In searching for specific files, one may also gain more peripheral knowledge of how the project is organized as a whole.

However, when it becomes too overwhelming to find all this information, Philemotte recommends talking to the people on the team who may have more knowledge of things, and to not be afraid of asking for help. Though it may not apply as much to open source projects, Philemotte advocates attending meetings where one can participate, understand and discuss goals and other activities that will help move the project along.

Philemotte notes that a longer-term, broader view of the project smooths things along, too, saying that it helps to realize the importance of providing maps and legends that can benefit others.

Other ways to make development less of headache include finding a good code editor to help read and write code — one that is “right for the job” and that you are comfortable with. Asking which editors other developers are using also helps.

“Prepare your environment,” advises Philemotte. “Find the project’s dependencies, like databases, queue system, mailing lists and so on.”

Philemotte also recommends running tests, as it will help you determine minimum requirements to develop and identify any missing configurations. In addition, you should sign up to the project mailing list and issue tracker. Next, one should also run the application on the available environment(s) to get a more solid idea of how it will perform, but Philemotte contends that you should only “test whatever [features] you need to test, or whatever makes sense according to your goal” to avoid wasting time.

After collecting as much information as possible about the project, it is time to read and plunge into the code base. After all of this preliminary legwork, you will also have become aware of the conventions to follow when you edit or add code lines, states Philemotte. When code is initially submitted, be available to answer any questions about it after submission. “Initially, when the code is written, it should be short and reasonable, as the main goal is to learn about the code base that is running,” says Philemotte. Again, it helps when diving into a code base to look for a goal, get a map of where things are, and to keep an active vision of organization and progress while expanding your knowledge. 

This goal-oriented approach is one that produces results, and is also reproducible. One can look at the issues and report them, fix a bug, or run a static analysis tool, review a pull request, or suggest alternatives to the problem, then repeat this process to generate a pattern for working efficiently, suggests Philemotte. Finally, he adds: “Keep it simple within the framework of the project, and know that you know how to plan your journey. Respect your limits, and if you’re blocked, don’t be afraid to ask.”