Fluent API Design for Human-Readable Code: Key Takeaways

Name: Human Readable Code - Computerphile
Uploaded: 2026-05-29T13:30:12+00:00
Duration: 22 min 51 s
Channel: Computerphile
Description: Summary and key takeaways on Human Readable Code - Computerphile: Summary & Key Takeaways, covering The Problem of Interpretation Comments often fall out of

Computerphile

May 29, 2026

•

22 min video

•

2 min read

YouTube video ID: SJocPm2E8eQ

Source: YouTube video by Computerphile — Watch original video

PDF

Comments often fall out of sync with code, creating two separate, potentially conflicting sources of truth. Traditional specifications lack a shared language, so engineers and stakeholders frequently misinterpret requirements. Running the application becomes the only way to verify understanding, which is costly when discovered months into development.

The Fluent API Approach

A fluent API lets developers use a mainstream language such as Java to write code that reads like an English sentence. By building a domain‑specific interface on top of existing language features, the code becomes understandable to non‑programmers while still being executable. The goal is to let anyone validate the logic of a test without needing to write code themselves.

“We’re really going to concentrate on making it readable for humans and not just for the computer.”

Practical Implementation

Write the desired English‑like syntax first, for example find all the cards that are spades and less than five and print them.
Define interfaces that represent domain concepts such as Choice and Action instead of low‑level types like List.
Implement methods that return objects (e.g., a Selection) so each call can be chained, creating a sentence‑like flow.
Hide the “plumbing” that performs the actual data processing—filtering lists, printing results—behind these interfaces.

Iterative development drives the process: compiler errors in IntelliJ highlight missing methods, prompting the addition of the necessary infrastructure while preserving the readable top‑level syntax. The speaker notes that building this plumbing typically takes an hour or two of initial effort.

“I really like driving it out from what I want it to look like rather than building it up and making it so.”

Strategic Value

When the readable layer serves as a test, stakeholders can verify that the system meets business needs, raising confidence in software correctness. The approach reduces communication friction in long‑term projects because the shared vocabulary emerges naturally during the design phase. Discovering and agreeing on terminology early creates a stronger alignment between engineers and business owners.

“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.”

Takeaways

Writing code that reads like English sentences lets non-programmers validate logic without writing code.
Separating the hidden “plumbing” from the readable layer keeps business-level tests clear and reduces the risk of misaligned requirements.
Building the domain-specific fluent interface in Java typically requires an hour or two of initial effort but pays off in long-term maintainability.
Defining domain concepts such as `Choice` and `Action` through interfaces creates a shared vocabulary that aligns engineers and stakeholders.
Iterative development—starting with the desired syntax and letting compiler errors guide implementation—streamlines the creation of a fluent API.

Frequently Asked Questions

How does a fluent API improve confidence in software correctness for stakeholders?

Stakeholders gain confidence because readable tests written in natural-language style can be understood and verified without code knowledge, ensuring the implemented logic matches business intent. This alignment reduces the need for late-stage debugging and lets teams detect misinterpretations early, as the same sentence that drives the test also serves as documentation for the requirement.

What steps are involved in constructing a fluent API in Java according to the described method?

The construction process starts by writing the ideal English-like statement, then defining interfaces for each domain concept, implementing methods that return chainable objects, and finally adding the hidden plumbing that performs the actual data operations. During development, compiler errors guide the addition of missing methods until the fluent sentence compiles cleanly.

Who is Computerphile on YouTube?

Computerphile is a YouTube channel that publishes videos on a range of topics. Browse more summaries from this channel below.

Does this page include the full transcript of the video?

Yes, the full transcript for this video is available on this page. Click 'Show transcript' in the sidebar to read it.

Helpful resources related to this video

If you want to practice or explore the concepts discussed in the video, these commonly used tools may help.

Clean Code A Handbook Of Agile Software Craftsmanship Recommended

This book provides foundational principles for writing readable, maintainable code, which aligns with the podcast's focus on human-centric API design.

Amazon →

Effective Java 3rd Edition

Since the podcast uses Java for its examples, this book offers best practices for writing robust and idiomatic code that supports fluent API construction.

Amazon →

Domain-Specific Languages Martin Fowler

This book provides a deep dive into creating DSLs and fluent interfaces, directly supporting the podcast's practical implementation strategies.

Amazon →

Mechanical Keyboard For Software Developers

A high-quality keyboard improves the physical experience of iterative coding and refactoring, which is central to the 'write the syntax first' approach.

Amazon →

Links may be affiliate links. We only include resources that are genuinely relevant to the topic.

Summarize another video

Full Transcript YouTube

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.
>> And is that like lots and lots of
comments and things like that or making
it verbose? How do we do that?
>> 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?
Then you've got two bits. one that's
comments for humans and one that's code
for the computer.
>> It's like putting sticky notes on
everything.
>> 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.
>> 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.
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.
>> At which point months have elapsed since
Yeah. Okay.
>> 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.
And so the program I wrote so far is
just says uh make a complete deck of
cards and then shuffle them.
>> 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.
>> 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."
>> Yeah.
>> And so what we'd like to do is I'd quite
like the code to look exactly like that.
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.
>> Okay.
>> 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.
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.
So here's my code like I wish it I wish
existed. We just got to make it so in.
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.
>> 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.
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.
And it's going to do something, but I'm
not sure yet.
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.
>> Yeah. A choice between
>> a choice.
>> 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.
>> S English word for it. Yeah. Okay.
>> 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.
And so far we won't say more than it
exists.
And spades can be a choice then. So I
can have a choice
spades and then this goes not red.
>> 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.
Let's make an interface called action.
And I'll make an action called
print them. And then we're almost there.
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.
>> 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.
>> So almost. Yeah.
>> 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.
Maybe is it a selection? It's sort of
the only you might select from.
>> Oh like a Yeah. Well a list
>> I suppose we've got. Yeah. But it could
be but sort of more conceptually.
>> Okay.
>> 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.
>> 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.
>> Um let's go for
>> option. No options.
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.
>> 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.
>> So I'm going to create this not rename
Let's do that. So that R is a method on
selections.
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?
>> Choices. No, I think that's Oh, yeah.
Well, that is a problem.
>> 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.
>> 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.
>> So another selection. Yeah.
>> And um then we can say Once you've got
that selection, you can do things to it.
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.
>> But the way we wrote the sentence was
select these things and print them.
>> So like a sort of sequencing
>> and then do this with it.
>> So would would you rather it said them?
Would that make
>> Maybe that would make sense. Yeah. Yeah.
>> 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.
And the thing you can ask selections to
do is to do actions.
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.
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.
>> 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.
>> Okay.
>> 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.
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.
>> So, then we're saying find all the cards
and it goes, yeah, okay, here's a null.
And then you try and do something else
with that and it blows up immediately.
>> 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.
>> that you that the person who you're
sitting with doesn't need to know about.
>> Right.
>> But they can see what it's supposed to
do.
>> They can see what it's supposed to do.
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.
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.
>> 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?
>> 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.
>> 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.
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.
>> And is there one last question perhaps
on this is that obviously we've done
this in this specific language in Java.
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.
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.
Another possible inter living in

Help & FAQ

Is it Possible to Block Childrens' Access to Social Media? - Computerphile

Computerphile

Jun 16, 2026

The Fluent API Approach

Practical Implementation

Strategic Value

Takeaways

Frequently Asked Questions

How does a fluent API improve confidence in software correctness for stakeholders?

What steps are involved in constructing a fluent API in Java according to the described method?

Who is Computerphile on YouTube?

Does this page include the full transcript of the video?

Helpful resources related to this video

Share This Summary

Embed This Summary