Understanding Through Documenting: The importance of seeing how your code fits into the bigger picture and how documentation can help facilitate that.

03 Apr 2018

By Tiffany Jann

Last month, I showed up to badminton practice hoping to have some fun, get some exercise, and make some friends. I instead made a fool of myself, but learned a lot from the experience.

I met a computer science major (highly likely, the badminton team is overwhelmingly CS), working in the same lab as me (highly unlikely). Turns out, he was the student my advisor had in mind when he asked me to finalize my code to serve as an example. So we talked about my code. The conversation went something like this:

Him: “I didn’t understand it.”

Now he had my full attention. I thought the code was clean and well-modularized with descriptive function names and even some comments. How hard did he try to understand it?

Him: “What does it do?”

At this point, I realized I couldn’t answer his simple question. I had no idea what this program, as a standalone entity, did. In that case, I could not have conveyed its high level purpose in the code or documentation, and he certainly was right to be confused.

I went into finals exam mode, trying to recall everything about the program.

Me: “Okay, so it turns A into B so that we can use B in C…” I paused.

I tried my best to quickly repicture the entire script and started piecing together what the functions achieve together.

Me: “We take this from A and call X on it to get A-prime, and then we call Y…””

Him: “Does it go from [high level space 1] to [high level space 2] or from [high level space 2] to [high level space 1]?” he interrupts, like he had a better idea of what my program does than I do.

Still unable to answer, I kept going through my memory of the code. Eventually, after a lot of starts and stops,

Me: “Yes, it goes from [high level space 1] to [high level space 2].”” He was happy with my answer, but I was well-aware of how close I was to failing to explain my work.

I knew that I could get caught up in accomplishing my tasks and struggle with understanding where my work fits into the bigger picture, but this was the call to action I needed to prioritize this problem. In research, getting tasks done is only part of the bare minimum–with so many research directions, how can anyone trust my research if I don’t have a clear idea of why I am doing what I am doing? The open nature of research means there is no clear path, so each decision needs to be well-justified.

That week, I took time to understand what exactly I was doing and why I was working on each task. I ramped up my documentation for that code to include a short blurb addressing what it does and what it is useful for, in addition to how to run the program. I realized that documenting my code in this way makes me think about the purpose of the code, and enables users to better and more quickly understand how the individual lines of code achieve the ultimate goal. I hope that by continuing to improve my documentation habits, I will become a better researcher and avoid embarrassing encounters like this in the future.