[Music]
Good afternoon everyone and welcome to
our second talk for our afternoon
session here at PyCon AU 2025. I would
like to introduce Sarah Reichelt. Sarah
has been programming since before most
PyCon AU users were born.
And while she may not consider herself a
teacher, she literally has written the
book on Mac OS Development for Mac OS
newbies. Well, four books actually.
Sarah's passion is trying to get more
people writing apps for Mac itself. So
her latest book, Escape from Tutorial
Hell, helps people get over that next
hurdle from beginner code to developer
in your own right. Sarah Raichel,
thank you very much.
[Applause]
Oh, good afternoon and thank you for
coming to my talk.
Um, I have to say, but I feel a bit of a
fraud standing up in front of you Python
people because I'm not much of a Python
person. In fact, I don't really use
Python very much except every December
when I struggle with Advent of Code.
But give me a few minutes to explain
what I do and then you'll understand why
I'm here.
So, in my day job, I grow yogurt-like
bacteria for use in making cattle feed.
And among my roles in that job, I am in
charge of the process control software,
which is mostly JavaScript, no.js, but
it does have a little bit of Python
involved.
As with any agricultural job, this is
seasonal, so I do other things.
I do consulting programming, mainly web
apps. If any of you have ever bought any
furniture at King Living, you will have
seen the showroom staff using my
software.
I also write apps for Mac and for iOS
using Swift.
So, I'm not really a full stack
developer. I'm more an untidy heap
developer.
Along the way, I learned that I really
like writing books. So, this started
when I was asked to contribute two
chapters to an existing book on Swift
UI.
And then I wrote two more books
specifically about Mac OS app
development.
One's for total beginners and the other
is for people coming from iOS
development.
My most recent book is called Escape
from Tutorial Hell. And that's why I'm
here today. The examples in the book all
use Swift, but the concepts are
universal and can be applied to Python
or to any programming language.
So what's the problem?
Well, you learn to code by learning the
building blocks. You learn how to use
variables, how to use loops, how to
write functions, how to write classes.
But then you get out into the real world
and things are a bit different.
You have to work on a complete project
and the gap between the building blocks
and the projects just seems enormous.
It's like one of those websites that
tries to teach you how to draw an owl.
you know, draw a circle, draw another
circle, and now draw the rest of the
owl,
but you're stuck in tutorial hell
because you don't know how to draw the
rest of the owl.
So, in this talk, my goal is to provide
you with some tools for making that jump
from tutorials to real life projects.
And I have four main steps I'm going to
follow along the way. project design,
project structure, documentation and of
course we got to discuss using AI.
So the first is project design.
Now we all love coding. So it's very
tempting to start by coding but that's
the wrong place to start. Start by
thinking
firstly the highlevel decisions. Well
first what project are you going to
write? Then what platforms is it going
to support? What language are you going
to use? What frameworks are you going to
import? And does it have a user
interface? If so, what's that going to
look like?
So, choose your project options. And for
the rest of this talk, I'm going to
imagine that I've been asked to write
the backend for an online store.
So, the platform is any web server.
Given my audience today, the language
obviously will be Python.
And for the frameworks, we'll choose a
server and we'll choose a database.
Now, this is a backend, so there's no
guey, but if there was, I'd stop at this
point and sketch it out. Doesn't matter
how rough your sketches are. That
visualization will really help you
design the rest of the project.
So now, what are the major functions of
our project? I'm going to start breaking
it down into chunks. So, we start off,
we've got the server component, we've
got the database component, and then
we've got the APIs for communicating
with the front end.
Let's keep going. The APIs, the three
main blocks of APIs, dealing with users,
dealing with the products, and dealing
with orders. So, already we've taken the
monolithic project and we've broken it
down into chunks. Now, if you're an
experienced developer, you've written
this sort of project before, that may be
enough for you. You may now be able to
look at each of these chunks and think,
I can visualize how to do that.
But that's fine if you can't just keep
subdividing.
Let's go into the database section. So,
we need to be able to create the
database. We need to be able to add the
tables. We need to be able to save data.
We need to be able to query the data.
So the goal here is just to keep
subdividing the tasks until you feel
comfortable with each of those tasks.
This next step may surprise you. Step
away from your computer. Go for a walk.
Have something to eat. Get a good
night's sleep. I guarantee you when you
come back tomorrow and reread your plan,
it will become better.
So this is not a coding talk. So I'm not
going to talk about the code, but I am
going to talk about how you structure
the code.
When we're learning to program, the code
that we write is one-off code. We write
it to demonstrate a point or we write it
to um complete an assignment and then
it's gone.
In the real world, you work on a project
that could last for years. So you have
to write code that you or another
developer can navigate and can read.
Then you have a project that you can
maintain.
The main aid to navigation is files and
folders. Divide your code up into
separate files and put these files into
folders so that you can find what you're
looking for. In our store example, we
have orders to process. So I have an
orders folder. Inside the orders folder,
I have a payments folder. And inside the
payments folder, I have a file for each
payment method.
Now, if PayPal changes their API, I can
find where that code is and fix it. Or
if we decide to add a new payment
method, I know where that file should
go.
Basically, each file should only contain
code responsible for one task.
We need the code to be readable so that
when we come back to it, we can work out
what it does.
Martin Fowler in his book on refactoring
wrote, "Any fool can write code that a
computer can understand. Good
programmers write code that humans can
understand."
Now, I think he may be overestimating
fools, but he has a point.
Don't write clever code. Write readable
code. Complex oneliners look really
impressive, but they'll waste your time
later when you're coming back to try and
find out what they do.
Keep your functions short. My rule of
thumb is that if a function extends over
more than the screen, it's got to be
split up. I never want to scroll to read
a function.
And finally, use a llinter or a
formatter to keep your code style
consistent. That'll really increase
readability.
Next up, naming.
And to paraphrase a joke that goes
around the internet, the hardest problem
in computer science is naming things and
off by one errors.
So when you're naming things, you have
to remember that you're going to be
reading this code maybe in a year's
time, maybe in five years time. And
while it may seem very efficient now to
use a short name that saves you a few
keystrokes, it's very inefficient later
when you're trying to remember what it
does.
Remember back in school when you learned
grammar? Or am I the only one old enough
to have learned grammar?
Those rules can apply to naming, too.
Variables are nouns. Username, total
cost, product size.
functions start with verbs. Doing words
like process order, save password.
Since code editors will all help you
autocomplete, there's no excuse for not
using long and descriptive names to make
your code more readable.
Here's a terrible example.
Now, it may have been quick to write
that, but imagine coming back to that in
a year and trying to work out what it
does.
I mean, the only thing I can say in its
favor is it doesn't use fu as a variable
name.
Now, here's exactly the same function
only with good names.
And each line reads practically like a
sentence.
So, which one would you rather be
looking at when you're reading somebody
else's code?
The other thing to remember about naming
is that it's not a one-off task. It's
something that is a live part of your
code you've got to keep working on. If
you come back to your project and
something is hard to understand, think
about how you can rename it to make it
easier to understand next time. And if
what a function does changes, change it
in the name to match.
Still on project structure, one file
that I add to all my projects is a notes
file. I use markdown, but it can be text
or anything you like. I work on multiple
projects at a time. So, this is to help
me get back to every project. So, I'll
write what I'm working on now or what
I'm going to work on next. I'll list the
known bugs. I'll say my future plans,
you know, for version two, three, and
I'll give links to anything that I think
might help me. Just whatever I think I
need to get back up to speed on that
project as fast as possible.
And finally, as far as project structure
is concerned, source control, which
these days basically means git.
So git is a tool that has saved me many,
many times. It's like a magic time
machine. And if you save snapshots of
your code, you can always revert when
you've totally broken everything.
And if you connect your code to one of
the big providers, GitHub, Gitbucket,
Bitbucket, GitLab, whatever, then you
get an off-site backup and you get the
ability to run your code on any
computer, which is really useful. So, if
you're not familiar with using Git, this
is one place where I recommend you do go
back and do a tutorial.
The next step on my escape route is
documentation. And this may sound
obvious or boring, but learning how to
read and write documentation effectively
is a vital skill.
Firstly, every programming language has
its own documentation with its own
style. So, you need to spend some time
learning your way around this.
Learn how to navigate, how to set the
version number that you're working with,
how to follow the links, how to search.
If you spend some time early in your
project to learn how the documentation
works, you really save time in the long
run.
Depending on your editor or its
extensions, you may be able to have some
of this documentation locally as well.
And that's really good because you can
see the help without having to interrupt
your workflow to get out into the
website and look for it. So, if that's a
possibility, enable it.
The other aspect of documentation is
what you write. And this will mainly be
in the form of comments. Now, some
people say if you use good names, the
code is self-documenting and you don't
need to add comments. Nope. There's a
certain amount of truth in that, but
comments can add more value.
Here's an example of a function with bad
and unnecessary comments.
Basically, every comment is just saying
what the next line does. But the lines
have good enough naming, so that's
useless. So, in fact, all these comments
are actually making the code less
readable by adding noise.
This is the same function, and I've
stripped out the boring, useless
comments, and I've added some new ones.
Firstly, we have a to-do reminding me of
an optimization that I want to do. and a
lot of editors can format or gather
to-dos or fix me in a useful way. So you
that's a comment that's used as a
bookmark.
My other comment is one that's giving
more information about how the returned
data is structured.
So don't comment the what, comment the
how or the why, or use comments as
bookmarks.
My final recommendation for
documentation is to save code snippets.
You can use a dedicated snippets manager
or a text file or anything you like. I
don't actually recommend using a bunch
of sticky notes, but that just seemed
like a good graphic to use.
It's so frustrating when you know you've
seen a way to do something and you can't
remember what it is. So, whenever I see
something cool online that I think one
day I'm going to need that, it goes into
my snippets manager. And if I've spent
ages researching how to do something, it
goes into my snippets manager so I don't
have to do that research again.
Okay, finally we get to AI, which you
know about half the talks here have been
about AI. So I'm not going to go into
any details of why you should or whether
you should. I'm going to tell you how I
use AI and how I find it helps me.
I started using GitHub Copilot about two
years ago. And at first I just used it
like a super code completer. So we're
all used to the code completion where
you start typing a variable name and it
fills it in for you. But GitHub Copilot
would go further than that. It would
finish the line or it would even suggest
another line. If you use good names for
your functions and variables, copilot
can extrapolate from those to suggest
more code, which has the added benefit
of encouraging good naming.
AI is great for explaining code that you
don't understand.
I had a Ruby script that was generating
all the different formats of my book,
and I don't do Ruby, so I didn't know
what I was doing.
So I asked Copilot to explain it to me
and it took me line by line through the
code and showed me what each of the
lines was doing. It's really good.
Another use is reminding you of syntax.
Now when working with JavaScript arrays,
I can never remember all the different
array functions. Is it splice or split
or slice or I don't know. So I'll write
a comment, you know, get the last three
elements of this array or delete element
four of this array. And when I press
return, copilot provides that syntax for
me. And yes, I should put that into my
snippets manager.
Finally, I use AI for generating sample
data. This is particularly good if I'm
designing an app with a GUI and I want
to see how it looks with some user data
already in place.
So after using GitHub Copilot for a
while, I moved on to using the cursor AI
editor. This is a fork of Visual Studio
Code with AI built into it. And the
benefit of this is that as well as doing
everything C-pilot does, it can access
the entire project, editing multiple
files at a time and even adding new
files if it needs to. And it adds a
chatbased interfaced option for lower
longer form queries. Now, I think
probably GitHub can do this now, but it
couldn't at the time. Anyway, I found
this to be great for filling in the
blanks in my expertise.
For example, I recently changed my
website at trolls.net to use a different
static site generator. And unlike the
ones I'd used before, this one didn't
come with pre-built themes. So, when I'd
added all my content and set up the
navigation, I was left with this rather
ugly site. And I thought, uh, now I've
got to get into the CSS, but I'm not a
CSS expert.
So, then, of course, it occurred to me
to ask the AI to generate my CSS. So, I
pointed it at my project folder and gave
it this prompt. Create a responsive CSS
theme with light and dark modes. It
should have a header with navigation, a
footer with links and copyright notices.
The homepage is a list of blog post
summaries, and each post has its own
page. The site is mainly text with some
images.
So, it didn't get it right first time.
It took me maybe three hours of asking
and reverting and adding suggestions and
asking for more features and tweaking
the colors and all those sort of things.
But finally it came up with this which I
was very pleased with.
So the AI had allowed me to take a step
back and instead of operating as a
mediocre CSS developer, I was a designer
who was talking to a very patient CSS
developer. And while I could have done
this myself, I would have got stuck in
how to do instead of being able to focus
on what to do.
Which leads me neatly on to this rule.
I don't know who wrote this, so I'm
afraid I can't give credit, but I love
it. Never get an AI to write code that
you couldn't have written yourself.
This just feels right to me. The AI is
saving me time by filling in the blanks,
but I could have done it all myself. It
just would have taken longer.
I could have written all that CSS, and I
can write code without super
autocomplete. But the AI makes it faster
and easier, and I still know enough to
know if it's right or if it's
hallucinating.
Here are my tips for working with AI.
Provide context. Now, a lot of people
have discussed context in this
conference so far, but the more
information that you give the AI as part
of the prompt, the better information
you're going to get back. So point it at
websites that deal with the issue you're
asking about. Tell it what files you're
looking at. Select the f the particular
function you're having a problem with.
Give it all the help you can so that it
can help you.
Iterate like with my website doesn't get
everything right first time. Sometimes
it gets dead wrong. But reword the
question or just ask again. You'll get a
different answer. And if it feeds you
something that creates an error, give it
the error and say fix it.
Use a new chat for each topic. And this
is kind of the reverse of point one
because we want to clear the context. So
the great thing about chats is that you
don't have to reiterate everything. You
can ask follow-up questions and it knows
what you've discussed earlier in the
chat. But when you're changing to a
totally new topic, you want it to forget
all that stuff and start from scratch.
So close that and open a new chat.
And finally, don't hesitate to ask it to
explain itself. Don't just accept what
it says. Ask it to if you don't
understand.
So that's my escape route. One, project
design before you start coding. Two,
project structure so that it's readable
and maintainable.
Three, documentation, existing
documentation and your own. And four,
using AI can be really helpful, but
check its work.
And finally, I want to emphasize that
I'm not opposed to tutorials. I do
tutorials. I read articles and books. I
watch videos all the time to keep up to
date. The problem is making that initial
jump from tutorials to projects. But
once you've escaped, never stop
learning.
So, thank you for listening to my talk.
If you'd like to contact me, my website
is tros.net and I'm at tro on mastadon.
And if you'd like to buy my book, come
up and grab one of my cards that has a
QR code with a special pyon discount.
And I'll put more of these out on the
sticker table, too. Thank you very much.
[Applause]
Thank you very much, Sarah. What a
wonderful talk. How insightful on how to
do things with confidence and uh
stability. Uh
the things I do to get a mug.
The things we do to get a mug. Yes. The
weather here is quite muggy indeed. Uh
so Sarah, thank you very much on behalf
of
Yay.
Once again for Sarah.
[Applause]
Uh friends, we do have some time for any
questions. Was there anyone that would
like to ask any questions of Sarah this
afternoon?
That's my son.
[Laughter]
It's important to have communication and
familial relationships to be
okay.
Are you proud of me? No. Um,
yes I am. there.
Was that the question?
Um,
when you're breaking down uh into into
your project structure,
how small do you go for those files?
Like some of them seemed like they might
only just have a single function per
file. Do you find that's tedious? Do you
do you then kind of move those up a
level and group a few of them together
or do you just run with that?
I when I'm writing in Swift, I have a
line limit. I don't like to go over 300
lines in a file. I find when I'm writing
in other languages that that is too
limiting, particularly in a like a
client side JavaScript where I don't
want it to be rushing off to the server
every time. So I'll have much longer
files. But yes, um we kept breaking down
the the the tasks, but a single file
could be a super task rather than each
of the subtasks.
Fantastic. Thank you. Do we have any
more one more here?
Yeah, thanks for the talk. The I like
that you said um don't use AI for
something that you couldn't have written
yourself. Actually my case I've I have
to admit I written like um a package
and I have no idea how it works but but
I was all interested is I know the
output so I made sure that all the test
pass but I don't know how it works so I
don't know pro and actually maybe a lot
of people would be doing something like
that. Look, I think we all do that to a
certain extent. I mean, none of us are
writing the machine code. We're all
taking in stuff that we don't know how
it works, whether it's Python itself or
or a framework or anything. So, at some
point, you've just got to trust that the
maintainers of whatever that is know
what they're doing, but you're
responsible for your you code, not for
what they code.
Excellent. We have time for probably one
more question if there were anything
further. Of
course, Sarah will be around for the
rest of the conference. We very much
appreciate your time this afternoon. Uh,
and we'll see you back shortly. Thank
you. Thank you.