This semester I have the pleasure of teaching a recitation of about 15 students the basics of software engineering as part of my TA duties (this Master’s degree won’t pay for itself, sadly). The course, 6.005, is taught in Java and is more or less the replacement for the old 6.170 Software Engineering Lab that MIT once offered.

One of the points I made during the first class was that programming is more about a conversation with other people rather than a conversation with a machine.

When one first starts learning to program, it really does feel like you are somehow talking to a computer. You type some words in a text file, save it, and when you run it, your silicon companion will either helpfully respond with the correct answer or squawk at you irritably and tell you to try again. For small programs that never grow beyond one-off scripts and toy projects, this is about the highest level of discourse that really ever gets reached.

As your projects grow in both the amount of work that needs to be done and in the time it takes to complete them, it becomes increasingly important to write your code not just as instructions to a computer, but as documentation to anyone else working on that code. You are just as much, if not more, telling the computer what to do as you are telling the next person to read the code what you mean to do. Sometimes, the next person to read the code might even be yourself in the future, well after you have forgotten the thought process behind the original code.

I’ve found that thinking of programming this way has inevitably led me to write clearer, better code and clearer, better comments. I imagine a colleague sitting next to me and then I pretend that I’m not allowed to communicate in any way other than the contents of the text file that I am editing. If the code is obvious, then my intentions are clear. When I do something that looks funny, or pause to think about a decision (perhaps some trade-off or compromise), I imagine the furrowed brow and confused expression on my friend’s face. These are then quickly remedied with an illuminating comment or bit of documentation.

Writing clear, understandable code isn’t a once-over kind of process after the fact, and it doesn’t have to be difficult either. I’ve found that by keeping my imaginary friend in the back of my head while I do my work, the output is inevitably better for myself and for others. Or maybe this is all just an excuse to justify having an imaginary friend.