# How useful is English (pseudocode and documentation) in aiding understanding?

I'm a freelance tutor working with high school students, giving them programming assignments in languages like Python, Java, C++, and others.

In recent months I've seen the value of using English - getting them to write documentation and also to write down rough drafts of their algorithms in pseudocode. I'm wondering what other teachers do with this. (I'll give an example with an Euler problem.)

The goal is to get them to think at a high level. Typically they like to dive into code. It's not concrete to them if they aren't writing code. I get it, developing a higher-level understanding is something that takes time. But I think I need to push it a little - they are just avoiding pseuocode and documentation past the point when they are really ready to use it.

One obstacle is their general writing abilities. The students who don't write well in any context, like English class, find it the hardest to write documentation and pseudocode.

To give an example, let's consider Euler 46, "Goldbach's other conjection" https://projecteuler.net/problem=46

This project involves testing different ways of adding squares and primes, in some kind of nested for loop. Typically they want to start out with details like

for (int n = 0; n < ???; n++)
{
for (int i = 0; i < ???; i++)
{
for (int j = 0; j < ???; j++)
{
??? generate square and prime S and prime P ???
if (2 * s + p == n)
break; // and do what then ???
}
}
}


Where I have put question marks is where they aren't sure what to put. But they begin wrestling with each place I have put question marks right away. That means they are struggling with low level details right away before they really understand the gestalt of the problem. Also they will throw in a break without having considered ahead of time how that will play out.

What I'm trying to get them to do is write pseudocode like this:

For every N, an odd composition number we are testing, in some range
For every prime P < N
if N - P is not twice a square, we found an exception. print or mark it


Of course this is a big leap, so I guide them to it gradually. (The benefits of working as a tutor and not a classroom teacher.) When they think at a high level, they can also see choices available to them. like maybe that pseudocode could be modified to be made more effcient.

For every N, an odd composition number we are testing, in some range
For every value 2 * S where S is a square
if N - 2*S is not a prime, we found an exception. print or mark it


They can reflect on the difference long before they have wrestled with the details of for loops. They can think about how they might efficiently test if a number is prime. Maybe they've seen before this idea of generating a hash set of primes and think about whether that's faster than trying to find out if a number is a square (which requires a sqrt operation).

Then there's documentation. The difference between something low level like

// set i to 0. increment i and stop when it's n
for (int i = 0; i < n; i++) {


and higher level like

// loop over possible test values (i)
for (int i = 0; i < n; i++) {


What I'm looking for from the answers is whether other teachers have found it useful to bring English into helping them develop higher-level understanding. "Chunking" concepts for example (thinking with high-level or abstract concepts). And how successful is this? Does it depend on a student's ability to use English in the first place?

• Communication skills are invaluable, but I've never understood the value of "pseudocode". In practice, you have to know a programming language to fathom it at all, and it's almost invariably some awkward pidgin of an existing language plus English comments, just vaguer but certainly not "higher level". Commented Sep 22, 2020 at 10:57
• I wonder whether your students wouldn't ask questions like the following. Firstly, what exactly are the formal features of this "pseudocode"? Is it block structures (and indenting or so-called 'horizontal layout' techniques) with the control statements (and the kind of block) stated freeform in English? A language must be shared - pidgins are less expressive, less widely spoken, and more ambiguous than established languages they are formed from. It's possible your students lack confidence in the usefulness of the pidgin, or lack a clear understanding of the concepts it employs. (1/2) Commented Sep 24, 2020 at 11:16
• Secondly, what exactly does "higher level" mean? Does it mean stating complex operations in fewer English words? If so, do you need to build their English vocabulary and communication skills? Are you providing a proper foundational understanding of these "high level" things (as opposed to skirting the specifics, on which an understanding would rest)? And again, do your students have confidence that this vocabulary is industry standard or widely spoken, or that (if you have devised it yourself) that it is credible and sufficiently systematic to be useful and worth spending time to learn? (2/2) Commented Sep 24, 2020 at 11:24
• If you're interested, I recorded a session today with his permission (taking a student through Euler 38 in C++). We use psedo-code and English to flesh out an understanding. youtu.be/jIquuSSdRSw This is an hour long and pretty slow for a third party observer, but if you are interested Steve, I really respect your desire to make this process concrete and would value your feedback. Commented Sep 25, 2020 at 0:02
• ... I don't if you have encountered this, but many of our students today have ingrained the idea that hard problems should feel hard and difficult to work through, so they don't look for an easier way. And, thinking with words and images is a skill that takes practice, and without guidance they may spend all their practice time making that harder than necessary. Certainly I did. It was only with pedagogic mentors as an adult that I started "looking for the easier way" Commented Sep 26, 2020 at 21:16

I believe that the core issue you're dealing with is that programming is too enjoyable, which makes outlining a program/writing pseudocode not interesting. It is a tough sell because in the time that students could be understanding a problem, they could be doing it (which is more fun). You need to demonstrate the value that pseudocode provides and what kind of issues it can avoid. This is easier to show off in big programs.

When I assign big projects and students come up with their own implementation that shows they didn't think about the problem, I ask them to start over. This is my compromise for not forcing them to write pseudocode. The idea behind starting over is they now understand the problem and the pitfalls well enough to start coding for real. In a way, all that code they wrote, was just a harder version of pseudocode.

I'm not sure what level you're teaching, but towards the end of AP CSA, the majority of my students have started a program over. They are resistant in the moment, but the following year, almost all of them gave thanks. Knowing how to start over is not the same as learning to write pseudocode, but both result in a better understanding of the problem.

• Interesting comment, "Programming is too enjoyable." Sometimes they are wrestling with a problem and really feel quite confused, which I wouldn't call enjoyable, but the only way they see to start work is to dive in and write code, because pseudo-code is too abstract for them to think of. And I think it takes time to be ready to think in the abstract so I don't want to push that too much. Commented Sep 19, 2020 at 22:05

Funny, I came here to look for advice on getting students to write pseudocode, because mine struggle so much to do it. So here is why I want them to do it. If I set the activity up properly, and they engage with it, then they will really be planning their program before they start to write it. There are different reasons people like to "dive in" to code. Sometimes an entire solution just occurs to you and there's no reason not to start right in. But sometimes, it's because you don't know any other way. Just start typing and see what pops out. This leads to "programming by perturbation", where you arrive somewhere kind of close to a solution by a mix of chance and lucky guesses, and just kinda change symbols here and there until it "works".

I've tried assigning flowcharts over the years, but I think pseudocode works better for my teaching style. I can explain more clearly what I want the students to try to do. They still resist, and because the little details (like for loop fiddling) are still more enticing to think about than the big picture of how the program will do its job, I still have to nudge them and encourage them to keep the birds-eye view. So for me (and perhaps this also addresses other comments on your question), it's not so much that pseudocode is really a great way to think deeply or at a high level. It's that insisting on a natural-language description of the problem and its solution seems to be an effective path toward my goal. And what is the goal? To make sure that the learners have a mental model of what their program should do—all or most of the way through, not just the first step, and perhaps even anticipating some tricky edge cases—before they start nesting up a bunch of for loops and break statements. That's the first thing, the immediate goal of the lesson.

Now to really answer your question, my experience suggests that learners can learn the most when they explain their solutions to others. This is not really possible to do, unless you've practiced the kind of communication we're talking about. You don't explain your program by reading the listing verbatim. You have to paraphrase it so that its parts correspond to your mental model, because the model is ultimately what you are conveying to the listener. In fact, I'm much less interested in whether students can produce programs that solve the problems I pose than in their thought processes along the way, which they can only convey to me by explanations in the natural languages we share.

• Thanks for this. I'm a little confused why you and Steve have objected to calling it high-level - okay so let's call it chunking. en.wikipedia.org/wiki/Chunking_(psychology) What you call the mental model as well as the English description involve chunking - combining several details in a single thought. That's a form of abstraction and a step toward grasping larger and larger abstractions. I call "abstraction" high-level, but maybe I'm using it wrong. You use the words "big picture" and a mental picture "all or most of the way through" which also sound high-level to me. But thanks! Commented Sep 28, 2020 at 21:23
• I like "programming by perturbation" - I see that a lot. I've actually seen it more in self-taught adults who come to me to learn to program right. I'm sure it's in a lot of your young students, too. Commented Sep 28, 2020 at 21:29
• I didn't mean that pseudocode doesn't require thinking at a high level. I meant that for me, the immediate goal is the planning. The practice with thinking more abstractly is just a bonus at this point. Commented Oct 1, 2020 at 4:38

Warning : I am not a teacher of any kind, just a developer and I will tell about by personal feelings/experience

For me when I write in pseudocode I write in my native language (not English but I am sure it applies for all peoples native languages).

My native language is the language I use everyday since I was born, this is a language I know really well.

When writing directly in a programming language you use a language that you don't know entirely and which sometimes (for low level languages like C or C++) forces you to think low level because there are specific rules.

When I was a student I always wanted to write code directly and never think beforehand. After acquiring some experience (especially with big/ complex programs), I understood that thinking of the code in an abstract manner helps a lot.

I think forcing to write in English might be good but it might be better for them to discover that by themselves. I they try to make complex programs they will have to write in English to understand what they are doing and then they will continue doing it.

• I understand your point about allowing them to discover it for themselves, but I think sometimes students need to be pushed a little to start doing something that maybe they wouldn't do on their own. They are ready - they are ready to do something new and make progress even if it's uncomfortable. Commented Sep 20, 2020 at 19:47