Coding with Jesse

Web apps that last

A castle made of sand

When you're building a new web application, or even a new feature, how can you ensure that you're not creating a nightmare code base that will need to be rewritten completely in a few years?

Some people will say it's hopeless to even try and write code that will last. I've even heard people suggest that you should aim to rewrite all your code every few years. That sounds like a very expensive, wasteful strategy.

In two decades of building web apps, I've seen many codebases start as a shiny new prototype and grow into a huge system. In some cases, they've become old, ugly, painful legacy systems that teams are begging to rewrite and replace. (And often those rewrites will themselves grow into ugly, painful legacy systems!) But sometimes a codebase will remain more or less unchanged a decade later, running smoothly as ever.

I believe there are some decisions you can make when writing code that will help it to last longer, and withstand the test of time.

Change is inevitable

Probably the one thing you can be sure of is that change will come. The goals of a business will change, and the people within a business will change. There will inevitably be features added, and existing features will evolve and be repurposed. The names of the products will almost surely change. So is it even possible to write code that doesn't need to change?

I think the key is in the phrase "If it ain't broke, don't fix it". Code that is fulfilling its task, that is doing what it's supposed to do, and is bug-free, is code that will last a long time.

Nightmare code

To understand how to write code that will last, let's think about the opposite: a nightmare codebase that demands to be rewritten. The worst I've seen is a web server written as a giant single file with thousands of lines of code. A system built like a house of cards, where changing one thing will break everything. Code that is very difficult to read or understand. Code that literally gives developers nightmares.

Unfortunately, this is often the kind of code that comes out of throwing together a quick prototype. A hero developer stays up late one night and churns out a first draft like a stream-of-consciousness. The next morning, the business owner is delighted to see their dreams come to life. Everyone's happy.

Then, they ask to change just one thing. Add this little feature. And this other feature. And now this user needs this other thing. And could you just change that other thing quick?

Months later, and this rough draft has accidentally become the foundation for a web application that continues to grow, held together with digital duct tape.

So how do you prevent this nightmare from unfolding?

Do one thing, and do it well

Modularity is extremely important in writing code that will last. And a good module is a piece of code that does one thing, and does it well. That one thing might be interfacing with a single database table. Or it could be handling HTTP calls on a single URL and passing the data to and from other modules that talk to the database.

I find generally that it works best when each module has zero, one or two major dependencies. With zero dependencies, you have a set of functions that receive input data, process it in some way, and return results. With one dependency, you have a set of functions that act as an abstraction or interface to that dependency. With two dependencies, you're writing code that bridges the gap between the two, acting as an adapter or controller.

More than two major dependencies, and you should ask yourself if there's any way to split things up into smaller pieces that are responsible for fewer things.

A dependency might not always be a program you have to install. Another module in your system is also a dependency. So is your business logic. I think about dependencies as anything that your module "knows about". This could even be the shape of certain data structures that might not have explicit type definitions.

The fewer things a module knows about, the more likely the module will be able to persist unchanged over time, because there will be fewer reasons to change it.

When your web application is built with small, independent modules that only do one thing, the chances are much, much lower that any of those pieces will need to be rewritten. And the chance of the whole application needing to be rewritten all at once drops to nearly zero. Even if you later want to do a major redesign, you'll find it easier to copy over lots of these older, simple modules to reuse in the new system.

Finally, a tangible example

Let's say you need to send out a Forgot Password email. You could do the whole thing in one file, but I would prefer to split it up like this:

  1. A module that knows how to actually send an email using AWS SES or something, but doesn't know the recipient, subject or body of the email. function sendEmail(toAddress, subject, body), for example.

  2. A module that knows about the subject and body of the Forgot Password email, but doesn't know who it's sending to or what the reset URL will be. function sendForgotPasswordEmail(toAddress, resetUrl)

  3. A module for the user table in the database, that has a function to generate a reset code, but doesn't know how the reset code will be used or even whether an email will be sent out. function createResetCode(userEmail)

  4. A module that knows about the URL structure of the site, and has a function that can generate a password reset link from a reset code. function getResetUrlFromCode(code)

  5. A module that ties everything together. It takes an email address, calls createResetCode, uses that to call getResetUrlFromCode, passes that to getForgotPasswordEmail, and sends the recipient address and email body to sendForgotPasswordEmail. forgotPassword(email)

  6. A user interface widget with a form, a text field and a button, so the user can type in their email address and click Send password reset link. When the form is submitted, it tells the user to go wait for the email.

  7. A module that is responsible for the server-side password reset part of the system. It receives the form submission, pulls the email address from the form data, calls forgotPassword, and then sends a success status back to the browser.

Here, only a few modules are likely to change. You'll probably see changes to the sendForgotPasswordEmail function, as well as the user interface widget. All the other modules I've outlined are very reusable, and highly unlikely to change, unless you change your email sending provider, or your database software, or something else major. Even in those situations, the code that needs to change is very isolated and easy to replace without affecting anything else.

You can even improve on this further, by having the contents of the email be database-driven, so that non-technical staff members can change the email templates themselves through an admin interface. But an architecture like this is a good starting point that makes those sorts of changes simpler to make.

A good start

If you get in the habit of writing more modular code, and splitting things up as early as possible, then the next time you're throwing together a quick prototype, you'll be able to lean on those principals in the process.

Instead of a giant ball of tangled dependencies and logic, you'll be building smaller, simpler, reusable components that can be used as solid building blocks. Some of these will be so useful and generic that you'll even be able to reuse them in completely different systems without changing them at all.

Published on February 19th, 2023. © Jesse Skinner

Trying to decide what to do next? Follow the light.

A tree growing towards the light

Happy New Year! I've been trying to come up with a New Year's resolution, and it got me thinking about setting goals, finding and following your purpose, and how this ties into some books I read this year.

TL;DR: If you're trying to decide what to do next in your life, in which direction you should expand and grow, maybe it helps to think like a tree and go where the sunshine is.

The purpose of life

The most interesting book I read in 2022 was The Romance of Reality, where Bobby Azarian does an amazing job applying Darwinism to the universe.

He says that the universe itself is a self-organizing system, with a bias towards increasing order, complexity and awareness. The idea is that the process of evolution was around before life emerged. Life formed at the bottom of the ocean at thermal vents, where tremendous amounts of extreme heat energy met extreme coldness. Eventually, the first forms of life emerged here to capture that wasted energy and put it to use.

Fast forward to the present, and now we have complex life everywhere we look, actively consuming any and all food and energy available and using it to maintain the structures of our bodies, our systems and our species.

As lifeforms, humans are sentient agents of the universe whose purpose is to use our awareness and intelligence in order to optimise the conversion of available energy into complexity and order.

It's not hard to see how true this is. So much of what we do boils down to consuming energy (food, fuel, heat) so that we can create more order (clean homes, growing families, bigger cities, information, content creation). Pretty much every job is related either directly or tangentially to this process, or optimizing the process.

We've even dug towards the centre of the earth and the centre of the atom in order to unlock and consume more and more available energy and use it to create increasingly complex systems and structures.

So how do you fit into all this? And how can you use this perspective and knowledge to live a good life?

Following your dreams

I just finished reading The Alchemist by Paulo Coelho. It's a story about following your dreams. It's about a shepherd boy in Spain who dreams about finding treasure at the pyramids in Egypt. Following the guidance of those he meets along the way, he goes on a quest to literally follow his dream and see where it leads.

I've always liked stories about following your dreams. I've always tried to follow my own dreams. Once upon a time, I was stuck in the proverbial office job, and dreamed of the day I could be working from home, setting my own hours, choosing work I found interesting. I dreamed about buying a house, getting married and having children.

I followed those dreams, and soon started freelancing. Several years later, I bought a house, got married, and now have the family and life I'd always dreamed about.

So now I'm looking to the future, wondering where to go from here. There are so many possibilities that it's hard to focus and hard to decide.

Thinking like a tree

We're all in search of our potential. It's not just about finding happiness, but also finding activities that won't burn us out, that are sustainable in every sense of the word.

A tree will put more energy into the branches that get more sunshine, because opportunity creates a void that must be filled. Nature abhors a vacuum.

Thinking about our careers, interests and opportunities, it's as if we are trees with branches growing out in many directions, and we are trying to decide whether we should grow in this direction or that.

Like a tree, we can feel the energy coming from each branch to decide whether it's getting more sunshine or less. Sometimes this process is described as market research, trying to establish whether there is demand for a particular enterprise. Is it time to hire an employee? Or write a book? Or start a non-profit? Or teach? Or make a video game? Or take time off and travel? Or just hunker down and work harder doing the same things as ever?

Energy can take the form of light, or heat, or money, but also inspiration, joy, excitement and motivation. Which activities will give you a turbo boost and allow you to grow and expand further? Which are a dead end? You can also see which of your branches are already giving you more energy back. And you can expand carefully, incrementally, to get more feedback, to see if these directions are the right directions for you.

They need not expand forever in any given direction. Maybe there's a ton of energy available to move in the direction of, for example, publishing one small video game. But maybe that's also where it stops, and going all-in on video game development would be a terrible mistake. Or, maybe it opens up a new opportunity, one nobody could see or feel from here?

Follow the light

Follow your passions? What does that even mean? Instead, follow the light.

What is shining brightest to you right now? Where are your branches expanding to, and which of those branches are shouting "Go this way!!" Optimize for excitement. Learn how to convert some of that sunshine into food, by bringing joy to others (aka "providing value") such that others will be happy to give you sunshine tokens (aka "money") for the joy you bring.

If something excites you, it'll likely excite others. Because you do not live alone in a desert. If you can capture a bit of that sunshine out of the air, you can make it available to the whole world. And when you do, more energy will flow back from the world to you, as if to say "Yes, keep going!"

Follow the light. Capture excitement out of the air and share it with the world.

Published on January 1st, 2023. © Jesse Skinner

Add Mastodon replies to your blog

You can now comment on blog posts on Coding with Jesse! I turned off comments years ago, because I was getting tons of spam. But recently, with my return to social media, I decided to integrate Mastodon to give people a way to comment on and interact with my articles.

Initially, I wasn't sure how I would accomplish this. Mastodon has a ton of servers, and Mastodon search can only search for hashtags, so how would I know whether someone commented on my article? And how would I integrate it into my website?

I looked around at how some other blogs were handling this, and came across Webmentions, and particularly, Webmention.io. It's a web standard for communicating interactions across web servers! Perfect!

I naively assumed that Mastodon would automatically hit my server with notifications any time someone favourited, boosted or replied to a post that contained a link to my site. But alas, Mastodon doesn't do that for privacy reasons (understandably).

Fortunately, I'm not the first one to run into this problem, and so there's a free service available that solves this problem. If you sign up for brid.gy, you can link your social media accounts, including Mastodon, and brid.gy will automatically send webmentions to your site whenever one of your posts contains a link to your site, and people reply to, boost or favourite your post. Essentially, your Mastodon posts become an anchor for all the interactions on your blog posts.

With these two services in hand, here's how you can integrate Mastodon into your website the way I did:

1. Sign in to webmention.io.

You need to sign in with your website URL, and your GitHub account. Also, your blog needs to link to that GitHub profile with either <a href="https://github.com/jesseskinner" rel="me"> or <link href="https://github.com/jesseskinner" rel="me">, to prove that you own the site.

2. Add webmention tags to your blog

When you sign in, go to https://webmention.io/settings. Under Setup, you'll see these two link tags:

<link rel="webmention" href="https://webmention.io/username/webmention" />
<link rel="pingback" href="https://webmention.io/username/xmlrpc" />

Copy these and paste them into the <head> on your blog. These will tell other services (like brid.gy) where they need to send webmentions for your posts.

Go to fed.brid.gy and, if you're like me, you'll want to click on "Cross-post to a Mastodon account", so that it'll integrate with your existing Mastodon account.

4. Post a link to a blog post on Mastodon

Try linking to your most recent blog post on Mastodon. If you already did this some time ago, brid.gy will scan your posts looking for links. You can also feed it a URL to a specific Mastodon post so that it will discover it.

Brid.gy will periodically poll your account looking for new interactions on these posts, and will send any new favourites, boosts or replies to webmention.io.

Note that your post doesn't count as a webmention - only the interactions on that post do. But you can reply to your own post as a way to trigger a webmention.

When I was setting this up, I was logged into both brid.gy and webmention.io, clicking the "Poll now" button on brid.gy and eagerly looking for interactions to show up. You have to have some patience here as well, as both services have a bit of a delay.

Once you see some mentions show up on webmention.io, you're ready to render them onto your blog.

5. Add the webmentions onto your website

Here's the trickier part. You'll need to hit the webmention.io API and fetch the mentions for your blog post. You can do this server-side, if you want. My blog is static, so I needed to do this client side.

Since the results are paginated, you can only get back 100 at a time. I wrote this function to help me retrieve all the pages at once, and sort the results into chronological order:

async function getMentions(url) {
    let mentions = [];
    let page = 0;
    let perPage = 100;

    while (true) {
        const results = await fetch(
            `https://webmention.io/api/mentions.jf2?target=${url}&per-page=${perPage}&page=${page}`
        ).then((r) => r.json());

        mentions = mentions.concat(results.children);

        if (results.children.length < perPage) {
            break;
        }

        page++;
    }

    return mentions.sort((a, b) => ((a.published || a['wm-received']) < (b.published || b['wm-received']) ? -1 : 1));
}

Then, I used the results of this to pull out four things: the favourites, boosts, replies, and also a link to the original post where I can send other visitors to my blog if they want to "Discuss this article on Mastodon". Here's how that looks:

let link;
let favourites;
let boosts;
let replies;

const mentions = await getMentions(url);

if (mentions.length) {
    link = mentions
        // find mentions that contain my Mastodon URL
        .filter((m) => m.url.startsWith('https://toot.cafe/@JesseSkinner/'))
        // take the part before the hash
        .map(({ url }) => url.split('#')[0])
        // take the first one
        .shift();

    // use the wm-property to make lists of favourites, boosts & replies
    favourites = mentions.filter((m) => m['wm-property'] === 'like-of');
    boosts = mentions.filter((m) => m['wm-property'] === 'repost-of');
    replies = mentions.filter((m) => m['wm-property'] === 'in-reply-to');
}

Of course, you should replace the link to my profile with the link to your own. I'm taking the first mention (after sorting chronologically) that is interacting with one of my posts, and linking to that post URL.

With those in hand, you'll have everything you need to render the replies, boosts and favourites to your blog. My approach was to render just the avatars of everyone who boosted or favourited my post, and all the replies.

One thing to watch out for is that the content of each reply is HTML. To be safe (paranoid), I'm running the HTML through sanitize-html to make sure nobody can inject sketchy HTML into my site.

6. Allow people to share posts without mentions

For any posts that don't have any mentions, I added a different button, "Share this on Mastodon". When you click it, it runs this code, which prompts you for your Mastodon server (inspired by Advent of Code's share functionality):

const server = prompt('Mastodon Instance / Server Name?');

if (server) {
    // test if server looks like a domain
    if (!server.match(/^[^\s]+\.[^\s]+$/)) {
        alert('Invalid server name');
        return;
    }

    const text = `"${post.title}" by @[email protected]\n\n${url}`;

    window.open(`https://${server}/share?text=${encodeURIComponent(text)}`);
}

Yay for Mastodon comments!

I'm really happy with how this turned out. To add some placeholders on my old blog posts, I posted some links to some of the more recent posts, so they interactions would have a place to live. For the older posts, I'm just relying on the share functionality.

I'm considering implementing some server-side functionality to replace either webmention.io or brid.gy in the future, so that the mentions live in my database instead of relying on a third-party service that may disappear one day. I think I could also skip the webmentions process by associating a Mastodon post URL with each blog post, and then using the Mastodon API of my server to periodically check for interactions and replies. Or maybe it could log in to my server and listen for notifications. But for now, this works really well.

So from now on, whenever I write a new blog post, like this one, I'm sure to share in on Mastodon and give a place for readers to ask questions or discuss the article. Check the end of this blog post to see how it all looks, and be sure to favourite, boost or reply to my Mastodon post so that you show up on the page as well!

Published on December 27th, 2022. © Jesse Skinner

Advent of Code 2022

I've been really enjoying working on this year's Advent of Code. If you haven't heard of it, it's a series of coding puzzles, two a day for 25 days, from December 1st to December 25th every year. It only started a few days ago, so it's not too late to catch up. Or, if you're reading this later, you can always go back and try it out at your leisure. But, it is a lot of fun to wait until midnight each day to see what the next puzzle is.

What's cool about it, is that you can use any programming language you want. You just need to take an input file, run a calculation based on the puzzle instructions, and come up with an "answer", which is usually a number of some kind.

You can use your favourite language to try to come up with an answer as fast as possible, or you can use it as an opportunity to strengthen your skills in another language, even a language you've never used before and want to try out!

You need to log in with GitHub, Google, Reddit or Twitter, and then you can download an input file for each day. You'll need to read the input file in to your language of choice, and parse and process each line of the file.

If you're really fast, you can even get on the leaderboard. But doing that requires completing the puzzles in just a few minutes at midnight EST so that you're one of the first 100 people to do so. I'm definitely not fast enough to even bother trying!

So far, I've been using JavaScript with Node.js this year. My approach is to pipe in the input into my puzzle solution like this:

node solution.js < input.txt

To do this, I'm using an npm library called split that simply splits a stream into lines, to make it easier to work with. Here's a simple example that just counts the number of lines in a stream:

import split from 'split';

// keep some variables in the module scope to keep track of things
let count = 0;

// read the input file as a stream from stdin (Standard Input)
process.stdin

    // pipe it to the split library, to split it into lines
    .pipe(split())

    // receive a callback for each line in the stream
    .on('data', (line) => {
        // do something with each line, in this case just counting
        count++;
    })

    // receive a single callback when the file is done
    .on('end', () => {
        // do something at the end, eg. console.log the output
        console.log(count);
    });

If you're interested, there is an online community on Reddit where you can share your solution and join in the discussion to see what others have done each day.

I'll be sharing my progress on Mastodon at @[email protected], so you can follow me on there for updates and commentary.

I've also been pushing my solutions to Advent of Code up to GitHub, so feel free to see how I've approached it, if you're interested. But no cheating! 😉

Published on December 4th, 2022. © Jesse Skinner

Why I love Mastodon

I quit Twitter at the end of 2020, and haven't really used social media at all since then. So when I heard in the news that others were ditching Twitter for Mastodon, I got really excited!

I signed up for Mastodon back in May 2019 and, at the time, I wrote on there: "I just heard about Mastodon a few days ago. I keep spelling it Mastadon. It's a really cool platform and architecture, and I would love to see it completely replace Twitter one day. Do you think it could?"

It seems like that time has come. Not everybody has moved from Twitter to Mastodon, but a large number of developers have, and that's what matters most to me.

A wild month

In 14 years of using Twitter, I never went viral. The closest I came was when I published my blog post Svelte is the most beautiful web framework I've ever seen. The tweet linking to that post received 40 retweets, which had my head spinning at the time.

Well, in the past month, I've had three toots that were more successful than that. And one of those went absolutely viral! I was excited about Mastodon and hoping all these new migrants would stay, so I wrote "Boost this toot if you're planning on sticking around Mastodon whether or not it becomes more popular than the birdsite.", and so far I've received 217 replies, 3,254 favourites and 5,765 boosts!

I also tooted a list of web developers worth following and that received 77 favourites and 52 boosts.

I'm not trying to brag, I just want to demonstrate that the reach and discovery on Mastodon is so much greater than Twitter. Part of that is that there is no algorithm on Mastodon, part of it is that people can browse "local" or "federated" feeds to find new posts from people they don't follow, so it's much easier for new users to reach a lot more people. I also find that the quality of interactions is higher, and the conversations more intelligent and engaging.

As another example, I tried putting a poll on Mastodon and Twitter at the same time. I had 7 people answer the Twitter poll, but 43 on Mastodon! This and other experiments I've done have cemented for me just how much more easily I can reach and connect with other like-minded people on Mastodon.

Whatever it is, I've definitely experienced a lot more joy interacting on this platform. It's wonderful that there are no ads, there's no company profiting off our use of the platform, and we can own our own content. It's not a new company trying to launch a startup to replace Twitter, it's a platform built on an open web standard that will surely be around for a very long time!

What is the platform?

As a web developer, I was excited to learn that Mastodon is actually built upon ActivityPub, a web standard produced by the W3C, the standards body behind other technologies you may have heard of, like HTML and CSS.

ActivityPub is similar to RSS but with pushing content instead of polling a feed. It allows web sites to publish content, and have other web sites subscribe to that content. When a new post is available, the content is pushed to each of the subscribers so that they immediately find out about it.

The world of systems that work with ActivityPub is referred to as the Fediverse. Mastodon is a Twitter-like interface built upon this platform. There is also Pixelfed, an Instagram-like platform, and PeerTube, a YouTube-like platform. Anybody can create new platforms that integrate with the rest of the Fediverse, just by implementing the ActivityPub protocol. There is even a WordPress ActivityPub plugin so that any WordPress blog can be followed by others on the Fediverse.

Mastodon Servers

If you've heard anything about Mastodon, you've heard about how you have to choose a server. This is a weird step for many people, at least compared to large corporate centralised social media, but it's what we already have to do for things like e-mail (though most people choose gmail.com). There is no central Mastodon server, so you need to choose one to get started. But the great thing is, you can move to a different server, and anyone who follows you will automatically follow your new account (though you can't move your posts). You can even run your own server!

One easy strategy is just to pick any server that is currently accepting new accounts, and then accept that you may well decide to move elsewhere once you get a feel for things and settle in and discover a server that resonates better with you.

You can go to the Mastodon website or instances.social to browse servers. You could choose one that is somewhat relevant to your interests or location, or you could choose one that is totally generic. Or just choose one that has a name that you like. Like email, it will be part of your address.

Some development-related servers include hachyderm.io, fosstodon.org, indieweb.social, front-end.social, and toot.cafe, though the last two are closed for registrations at the time of writing this.

Back in 2019, I started off on toot.cafe, but decided the next day that I'd rather be on a bigger, more popular server, so I moved to mastodon.social. But earlier this month when I started using Mastodon heavily, I actually decided I'd rather be on a smaller server focused on web dev, so that I would have a "local" feed more useful and interesting to me, so I moved back to toot.cafe!

Migrating to Mastodon from Twitter

If you were already active on Twitter, you'll be glad to know there are tools to help you migrate. I highly recommend you check out Movetodon, where you can log in with both your Twitter and Mastodon accounts, and you can search for and automatically follow people. Of the 1025 people I follow on Twitter, I can find 164 of them on Mastodon, and more are moving over every day.

If you do decide to move over, be sure to put your new Mastodon address in your Twitter bio, so others can find you using automated tools as well.

I really hope this migration sticks, and so I think the best thing we can do support it is to participate as heavily as we can on there, to follow interesting people, to boost interesting posts, and to be active and contribute to the conversation so that others enjoy it there and stick with it too.

Follow me!

If you'd like to follow me, you can sign up for Mastodon (or another Fediverse server) and follow me at https://toot.cafe/@JesseSkinner. I hope to see you there!

Published on November 27th, 2022. © Jesse Skinner
<< older posts newer posts >> All posts