Stating the Obvious

One thing that the scientific code review pilot study has highlighted is how much perspective matters to collaboration. Over time, professional software developers (including scientists whose primary role has shifted to software development) build up an overview of how software works and how to make working software. They integrate skills and knowledge, building up a standard vocabulary of terms, tools and conventions, as well as a practical repertoire that it’s easy to take for granted.

Most scientists, on the other hand, don’t have such an overview. They are just getting a job done, wading around in the nitty-gritty of code development, focused almost entirely on the purpose the code serves, rather than the code itself. They often lack the integrated understanding and skill that comes with experience, which means that it’s often very useful for mentors to actually state the obvious. As one participant in our study said, “Everyone has some intuition about code… but it’s nice to have this laid out in a formal manner.”

How to make the transition from an in-the-trenches perspective to an overview is usually not clear to the scientist in the trenches. “Stuff that seemed like overkill makes sense now … A lightbulb finally went off:  I understand how other people look at my code and how to make it work.”  And what basics to articulate—where to look and how to look—is often not clear to experienced developers looking down from the stratosphere. If the two are going to collaborate, then at some point the different perspectives must be acknowledged and bridged.

This may sound obvious, but it’s not. And social mechanisms (courtesy, deference, avoiding embarrassment) tend to obscure perspective differences. Good teachers know they need to engage first with students’ perspectives in order to help students expand and refine it. The lesson for the pilot study is that it’s useful to articulate collaborators’ perspectives explicitly for both sides, and equally to help establish appropriate expectations explicitly.

This observation isn’t new: most notably, Judith Segal discussed it in her 2005 paper, “When software engineers met research scientists: a case study“. That work found two problems with applying industrial software engineering practices to science:

  1. They demand an up-front articulation of requirements, whereas the scientists had experience, and hence expectations, of emergent requirements.
  2. The project documentation does not suffice to construct a shared understanding.

These insights have been reflected as complementary wishes in the conversations we’re having midway into the pilot study. For every mentor who says, “I wish I knew more clearly what the scientists are expecting,” there’s a scientist who says, “I wish I knew what it’s reasonable to expect.” The articulation of expectations—about goals, obstacles, time commitment, speed of response, frequency of communication, assumed knowledge, etc.—is particularly important in achieving a shared model of what’s needed, and in developing rapport between the collaborators.

One concrete step we can take to help here is to show scientists what it actually looks like to do a code review—not just the end result, but the process an experienced developer goes through. To this end, we have asked a couple of mentors to create short screencasts of themselves going through a couple of pages of code they have never seen before. It may be a bit late to help the participants in the current pilot, but we hope it will help those who join the next round, and the community as a whole.