How Do You Write Programs So Non-Programmers Can Read Them?

Posted on June 23, 2008
Filed Under Programming, Software Development |

The Setup

In my final semester at TCNJ, I researched cryptographic hash algorithm with a math major. His programming experience was extremely limited: he had only programmed using Matlab, so he knew what functions and variables were, but that was the extent of his knowledge. In school I was a math minor, so we had a common ground for communication. However, part of my job was to actually write the programs that our research needed. Not only that, but the math major had to be able to modify what I had written in meaningful ways. I needed to write the clearest code that I had ever written.

So how did I do it? Language, Good Names/Comments, Structure, and Examples. Basically, all of the ordinary tools for making code more readable to programmers.

Language

I had a few criteria for selection:

I ended up choosing Python. First of all, downloading it and installing it on any OS is a piece of cake, running a Python file takes exactly 1 step: fire up the interpreter with the file as an argument. Second of all, it’s essentially executable pseudo-code. The syntax necessary to write a Python program looks very clean, and the indentation of Python forces a certain level of readability.

Third, I’ve never explicitly "known" Python, but I’ve always reached the "get things done" level of competency within a day of picking it up for a project.

I ignored Java and C++ because getting the compiler tools installed on new Windows machines is a hassle compared to Python, the installation is in 2 steps, and there is just more syntax for the newbie to read. YMMV, but I’ve always picked Python back up quicker than I’ve picked up Java or C++ after a long hiatus, and I "know" Java and C++.

Good Names/Comments

Extensive comments obviously helped the project. Normally, I describe what a function does at a high level, and then comment any tricky parts. This is enough for programmers, but it turned out to be insufficient for non-programmers. I showed my partner some C++ code in the beginning of the project using this technique and he didn’t understand how it worked.

At the beginning of each file, I added a description of the structure, and pointers to where he could find key parts of the code. At the beginning of each function, I commented the hell out of it, describing what it was supposed to do. At every logical sub-section of the code, I left a comment describing what it accomplished.

The best addition to commenting was using good names: consistent case, minimize abbreviation for the most useful names, and consistent naming across functions.

Structure

Every file that I wrote had to have the same general structure:

Since everything was always in the same place, my partner never had to look hard to find what he needed.

Examples

The best thing I did to talk to my parter in programming languages was to implement hash algorithms that he already understood. For example, here is my implementation of SHA-1 [.txt file due to hosting limitations]. I sat down with him and made sure that he knew how to run it, and from there, let him on his merry way.

The Result?

"Actually, it was a lot clearer than I thought it was going to be"

The code was a success. He was able to modify and read it successfully, and do everything that needed to be done.

Is This Relevent to Ordinary Programming?

No. I haven’t added anything new to the discussion, only approached an unusual situation with the usual solutions.

Popularity: 10% [?]

Comments

Leave a Reply