Human Readable Code - Computerphile

Added: 2026-05-31

[00:00:00]I thought what we'd talk about today is like programming, but we're instead of just trying to get our program to function correctly, we're really going to concentrate on making it readable for humans and not just for the computer.

[00:00:11]>> And is that like lots and lots of comments and things like that or making it verbose? How do we do that?

[00:00:17]>> We could have lots and lots of comments, but the thing with lots and lots of comments is it quickly gets out of sync with what the code itself is doing. And it's not actually the same thing, is it?

[00:00:25]Then you've got two bits. one that's comments for humans and one that's code for the computer.

[00:00:30]>> It's like putting sticky notes on everything.

[00:00:32]>> So something good is like oh yeah that's you know what it's like that sticky notes wrong but everyone knows that sticky notes wrong and you actually have to do this thing instead.

[00:00:41]>> The reason I was thinking about this was that you know typically if you're a software engineer you're building something for someone and they have a set of requirements that they need uh and they know all about that but they probably don't know about computer programming. And if you're the software engineer, you know hopefully all about computer programming, but naturally you're not going to understand exactly the details of their business or whatever it is that they're operating.

[00:01:02]So we need to have a good collaboration and it would be helpful if we had one thing that we could talk about together that we would be able to say like, oh yeah, you know that this is what we're doing now and and that's right and that's wrong. And so kind of traditionally someone would write a big document, give it to a programmer who'd read it, but then there's a bit of interpretation and then they go away and encode it in the special computer programming language. And the only way you could really check whether or not the system, you know, they'd understood it correctly is to sort of run the application, try it out, and then be like, oh, well, it doesn't work quite right in this this particular case. Something something's wrong.

[00:01:39]>> At which point months have elapsed since Yeah. Okay.

[00:01:41]>> Exactly. And so it would be nice if we could instead have a way where people could sit down together and actually look at the code and see like okay is this right or is that oh maybe we should change it like that. But naturally the way we typically use programming languages it's their kind of mainstream languages are designed to solve all problems but they're not particularly tailored to any particular problems. And so there is a class of thing called domain specific languages where we can build custom programming languages that work for particular problems. There's quite a lot of work to build one of those. You can imagine building a programming language. It's not a trivial task. So you wouldn't imagine that every software developer is going to do that all the time. So what I thought we'd look at today is whether we could take a mainstream programming language and do a little bit of you know as we're thinking about programming just try to make this human readability like absolute foremost in our mind and see if we can make the code read in a way where someone who's not a programmer is going to be able to read it and maybe not write it but at least validate like yeah that's exactly what I meant or no that's wrong and we should change that in that way. I thought we could do something about uh like decks of cards. And you could imagine that I might uh you know have a deck of cards. I'm going to shuffle it and we want to do certain things with it. So we might want to look for all the ones that are spades or we might want to find all the ones that have um you know value greater than five or all the ones that are spades and greater than five or and then we might want to do something like you know print them out or do some other stuff. There's a variety of things and if if you were u you know it's not a really um practical example but you could imagine you might have a set of things you might want to do. I might be writing the program to try to do it and I might want to check with you like oh is that is that what you wanted or oh you wanted something different from that okay let's just change it and for us to be able to talk about that bit of code to pick a mainstream programming language to work in that's definitely not tailored for this uh we do some Java >> it's pretty widespread uh lots of people writing that in the world not very fancy in any way um and so what I've written so far if people can see on the screen is I've got uh just something I made a thing to represent a card and I made a thing to represent a suit. I'll open that up just to say so and a thing to represent a deck where we can just say this is a complete set of cards. Uh we don't really need to look in here anymore, but that's just the sort of basic stuff we're going to work with.

[00:04:07]And so the program I wrote so far is just says uh make a complete deck of cards and then shuffle them.

[00:04:13]>> And that was just using kind of in-built shuffling stuff that we've got in the language. There's nothing special that we've done here. And then I might want to write down one of these scenarios that we just talked about like um let's see. So let's say we wanted to I'll write it just as a comment like in an English sentence, >> right? Okay.

[00:04:30]>> So what about find all the cards that are spades uh less than five and print them. You know, that might be an instruction you might give me to write in the program. And so I could go and write some code that would do that, but it would be hard for you to say, "Oh, yeah, that's correct."

[00:04:51]>> Yeah.

[00:04:52]>> And so what we'd like to do is I'd quite like the code to look exactly like that.

[00:04:56]Maybe not exactly exactly like that, but as close as we can get it. And I think that's something that often we don't think of as a primary thing when we're programming. We sort of map it onto the language of programming like while loops and >> if this is that then do that, >> all that kind of thing. But I wonder if whether we can make something that that looks like this. So what I try to do then is like well let's try and write the code like that. It won't work but let's just try and find the right shape and then see if we can make it work.

[00:05:25]>> Okay.

[00:05:26]>> So maybe we would have in Java we've got functions. So we could try a function that's like find all the and then cards is a thing that we've already got in the program. So maybe I could say maybe we could pass that into this function and then what comes next and they say that are spades and then actually I can imagine that spades might be a thing we might want to change here. So you could imagine a different thing we need want to do is say find all the cards that are diamonds. So so maybe this is a thing where we want to be able to pass in an option here. So maybe I'll put it in some brackets to say we might have a function here where you could pass in something different. And we also want to say that it's less than five.

[00:06:10]Again, five feels like a thing that it's a bit >> sometimes you might want to say less than six or less than it. So let's try something like less than five. And these two spades and less than they feel like criteria for selection or something like so they're kind of the same sorts of things. So I've passed them in both to this that are and then once we've found them what do we want to do and then we say uh and and again we we wanted to print them but I can imagine some other things we might want to do. So let's say I'm going to and print them. And because it's Java, I've got to put a semicolon on the end.

[00:06:52]So here's my code like I wish it I wish existed. We just got to make it so in.

[00:06:58]But because we started this way to say like not how is the code going to end up, but >> this is what I want it to be like. And now let's manipulate the programming language to make it like that.

[00:07:08]>> So what I could define functions to be those things, >> right? Yeah. So rather than saying like what functions have I got and let's build up my program I want to start with like how do I want it to read in a way that we can agree and at this point you could even say that that's wrong even though it doesn't doesn't work yet you could still say oh no not spades right or something and so we could fix it at this point >> and then we could make it so once we know it's right so the slightly tricky bit is we need to make it work uh so we can define some stuff right so one of the things I'm using intelligent J here with my Java code. It tells me in red that some things do not exist. So we could make those. So let's see. First of all, it's uh complaining a bit about this less than thing. So let's uh let's first of all make a function less than and just to stop it complaining more than anything else. So less than's a function that takes a number and uh well don't actually know what it does yet, but at least I've stopped it complaining about that thing. And then spades uh is a thing.

[00:08:15]Let's do find order first. That's going to be finder is another function. And it takes some a list of cards, which is a thing that we already have in the program.

[00:08:30]And it's going to do something, but I'm not sure yet.

[00:08:34]Uh and I have to tell it. Oh no, it's a list of card. There you are. So, it's getting a bit better. We still got some red things. Uh, so we've got something which is spades and we've got something that is print them. So, spades, we talked about it being like um a criteria or a a selection or a constraint or something like that. Which one of those feels like the >> Well, like I mean it's it's an option, isn't it, of of the four different potential suits? So it's uh something you want to you want to choose.

[00:09:09]>> Yeah. A choice between >> a choice.

[00:09:11]>> What about that? So let's say that like let's invent a thing called a choice and put it in the program because that's the word that we've agreed makes the most.

[00:09:18]>> S English word for it. Yeah. Okay.

[00:09:20]>> So uh we're going to make a thing. I'll make um an interface which is just saying like this is going to define choice but we're not really going to say much about it yet but it's going to be a thing that's in the language.

[00:09:31]And so far we won't say more than it exists.

[00:09:35]And spades can be a choice then. So I can have a choice spades and then this goes not red.

[00:09:45]>> Um and then print them in a similar vein. I feel like print them is uh like an action we might want to do when we've made our our selections. So let's make a thing let's do the same thing.

[00:10:00]Let's make an interface called action.

[00:10:05]And I'll make an action called print them. And then we're almost there.

[00:10:15]We've just got to make this function called that r. This one's a little bit more complicated >> because we're working in Java. It's an object-oriented language. this that r is comes after a dot and so it's a method on some object. The thing that we didn't talk about so far but when I originally wrote it out you know I wrote it out in an English sentence left to right and then we wrote a line of code that looked a bit weird because it's quite it's it's the one long line. Yeah.

[00:10:46]>> It's not a series of statements that say first of all do this then do this thing do this thing. And so this is what we would like a fluent design, a fluent API design. And so that means that we're trying to say like let's write it like it's a sentence, but we got to do a few little bits of manipulation to make it so that it will still execute in the right way. So we need a thing that find all the cards is going to return us to which we can do something called that R which is like a refinement or something. Okay.

[00:11:18]>> So almost. Yeah.

[00:11:20]>> Yeah. So it's so it will be like either something that is filterable or I thought about it as being like um a selection or something like this. So maybe find all the cards has to give us back um a selection.

[00:11:37]Maybe is it a selection? It's sort of the only you might select from.

[00:11:41]>> Oh like a Yeah. Well a list >> I suppose we've got. Yeah. But it could be but sort of more conceptually.

[00:11:47]>> Okay.

[00:11:47]>> Because I think a list is a programming type of thing. Okay. So it's a yeah a well a sort of yeah the word can't think of it.

[00:11:56]>> Yeah. So this I mean that's a sort of interesting point is that as we were developing it together we'd be like what is the word for that and so just trying to tease out a little bit >> define a common terminology >> so that in future we'll be able to talk about those things and oh yeah that's what that is.

[00:12:13]>> Um let's go for >> option. No options.

[00:12:22]Um it's >> I'm I'm imagining in a large corporation a big meeting about this one specific word a whiteboard a lot of pens >> and people coming >> which I think you know can be helpful in some cases. Um so let's go for let's go for selection. It's not quite right. We could refine it later if we but let's I'm going to go with uh selection.

[00:12:55]>> And so what we have to say is that the find order method is going to return us a selection and that means that that R is a thing that we can do to selections in order to refine them.

[00:13:11]>> So I'm going to create this not rename Let's do that. So that R is a method on selections.

[00:13:23]Uh so let's that R and it takes so now we've oh now we've passed in two choices. So actually we could say that it takes a number of choices and it's complaining about this. Why is it complaining about >> choices?

[00:13:48]>> Choices. No, I think that's Oh, yeah.

[00:13:50]Well, that is a problem.

[00:13:53]>> It's complaining here because this we said was a function that returned void like it returns nothing. But actually we want it to make a choice.

[00:14:01]>> We want it that to be a choice. So let's say that and we're getting pretty close now. So now we're going to say okay and is another method. This should be a method on whatever that R returns which we can figure out in a minute. Um that R returns void at the moment. So it's going to return let's make a smaller selection. So you started out with a a selection of cards. You refined it a bit. Now you've got a smaller selection.

[00:14:28]>> So another selection. Yeah.

[00:14:29]>> And um then we can say Once you've got that selection, you can do things to it.

[00:14:35]And the thing that's perhaps slightly unusual here is that normally in programming, if we used a word like and, we'd be thinking about like logically composing them.

[00:14:45]>> But the way we wrote the sentence was select these things and print them.

[00:14:50]>> So like a sort of sequencing >> and then do this with it.

[00:14:54]>> So would would you rather it said them?

[00:14:57]Would that make >> Maybe that would make sense. Yeah. Yeah.

[00:15:00]>> So we could change that. So, okay. So, let's then print them. And so, again, we could just, you know, making sure we're understanding. And then I got to make a method called then, which is a method on selection. Is it going to do that for us? Yes. Here we go. So, let's create a method that of a thing that you can do to selections.

[00:15:17]And the thing you can ask selections to do is to do actions.

[00:15:22]So, as long as you've got an action, >> then you can say, okay, then do this action. So the thing we haven't done so far is we haven't actually made it work.

[00:15:32]Well, let's start at least and let's let's try doing some of it to try to make it work to prove that we we're not just sort of uh arranging debt chairs that we can actually make this this work.

[00:15:42]>> So one thing I could try to do now is to run it. Obviously it's not going to work but it will help us to find out where the where the problems are.

[00:15:49]>> Okay.

[00:15:50]>> So uh I can run my program. So let's try and run it. Okay. and it goes wrong and it says there's a null thing on line 21.

[00:16:01]What is that? So, okay. So, somewhere in our long line, it went wrong uh because it was null. And basically, what I think is happening here is that find all the cards is a function that we have defined, >> but it just basically returns null.

[00:16:19]>> So, then we're saying find all the cards and it goes, yeah, okay, here's a null.

[00:16:23]And then you try and do something else with that and it blows up immediately.

[00:16:26]>> Of course. Yes. So you can work your way through the line of code and put all the if you like it might not be the right word but the back end in >> Mhm.

[00:16:34]>> that you that the person who you're sitting with doesn't need to know about.

[00:16:37]>> Right.

[00:16:38]>> But they can see what it's supposed to do.

[00:16:39]>> They can see what it's supposed to do.

[00:16:40]And if you get the first one working, then we could kind of hop up to the top level again and say, "All right, now you want to do another one that's about diamonds." Or now you want to do this.

[00:16:50]Oh, now you've got things that are less than eight and more than three and I'll spate. So, and at that point, hopefully we'd be able to keep going, but without having to write any more of this plumbing stuff underneath. we would have spent maybe I don't know an hour or two getting these plumbing bits together but developing almost like our own custom programming language that allows us to talk about uh you know in this cases selections of cards but in other cases student records or retail transactions or insurance rates or whatever it is >> using the terminology that you know we've agreed on and that is sort of meaningful to both of us >> so that I'm not using programming words to represent things and you're talking about things in you know their business terms and we don't so we could easily have a misunderstanding there where I think a certain word means something and you actually have a particular special meaning for that >> this way we begin to get it so that the program uses at least at this level all the words from our agreed shared vocabulary and it doesn't use any programming words and I think when we get to this and if we push on this approach quite a lot we can start to develop more and more of our code at the level where we could talk about it and then there'll be a layer underneath that we don't talk about together because that's the more of the the plumbing and the wiring and the infrastructure that we're building on in order to make it work.

[00:18:15]>> I suppose in the same way as somebody who perhaps asks for a house to be built and they want a plug socket here. They don't need to know how the wire got there but they do want the plug socket here. Is it that sort of a thing? I think that or they would be able to talk about um I don't know maybe that they need a two pin plug or a three pin plug or a USBC charger or something like this but yeah behind the panel >> how that works is not >> important but at least you need to be able to communicate with your electrician in that case about with a certain agreed vocabulary of what one of those things is versus what one of these other things is so that you get what you want. seems there's a lot of effort going in to making sure that we can communicate about this code. Is it really worth it? Shouldn't I just give you a specification say I need the code to do this and come back in a month and hope that it works?

[00:19:00]>> I think it's hard to say that it's worth it all of the time as you were rightly say like we had to put a bit of effort into building this. But hopefully if it was a domain that we were working in a lot of the time, so say we did work in a company and we had a whole bunch of features that we were going to do about trading strategies or whatever it was, we'd have to do these kind of changes all the time. And actually having a nice neat language to be able to express them quickly and easily would be a good thing. If we were just doing oneoff like something that's totally different to everything else in the system, maybe I wouldn't go to this length. But I think if there's something in the core that we're going to work on a lot, I think it can be worth it to do this.

[00:19:37]>> And it seems like you're putting a lot more effort in than I am. I think it's almost like you're making this fit. What I is is that >> I think at this point that's true, but I think if we came back in a week and you said, "Oh, actually there's a new feature and we need to do um something with, you know, particular hands of cards." And like, "Oh, okay. Well, actually, we've already defined quite a lot of the language stuff last week, so we don't have to go through that again.

[00:20:03]Hopefully, we've kind of built ourself a little language that describes very well our problem. And hopefully writing the new bits is actually even quicker than it would be if we kind of wrote them all out by hand in the code. So, it's a bit of upfront effort maybe. in a but I think also as we talked about the discovery of the terminology and the meaning of the concepts and what those things really are that's a valuable bit of insight that we get from having the discussion in trying to build it in the first place is anybody really using this is anyone doing it >> I think there's a small set of people who are doing it in their implementation code developers always talked about trying to write clean code I think this kind of you know readable code I think this takes it a little bit of a level beyond but I think the place where it's really like comes into its is if you are writing some tests to test your software. So typically today we'd often write a whole bunch of tests to make sure our software is correct. If your test is very comprehensible and can be validated by the person who wanted the system to say this test is correct and it passes, be pretty sure your software is correct. If you've got a test that passes but no one understands exactly what it means, it's hard to have any kind of real confidence in that. So if we can spend this effort on building tests that can be validated by me being able to show you the test that we've written for the system, you saying that's the right test or actually in that case that's slightly wrong and it should be this and then we run that test and that test passes then the core of the system like I have good confidence that we're building the right thing for you then.

[00:21:32]>> And is there one last question perhaps on this is that obviously we've done this in this specific language in Java.

[00:21:37]Is it portable or is that only the same problem as any code that you'd have to >> the the little language we built is not portable? And if we we could do the same kind of thing in Python, in JavaScript, in C, we'd have slightly different tricks and techniques that we'd use to kind of build the language. But I think you could have the same kind of philosophy of I'm trying to write the code. So at least at the top level of the description of the problem is very humanf facing and let's take advantage of the features of the language whatever it is to try and make it so rather than kind of building it back up from the bottom saying well here's how I express the problem in my language and this is what it looks like. So I really like driving it out from what I want it to look like rather than building it up and making it so.

[00:22:30]So here for instance one possible interle is that let's say that I execute the right to X first so this one and then the right to Y. So the two rights are executed before I move on to the two reads. As a result both reads will observe the updated value and they will both read one. So I can read one.

[00:22:49]Another possible inter living in