Forem: Hugh Jeremy

Time-Independent Dates in Swift

Hugh Jeremy — Thu, 07 Dec 2023 00:23:26 +0000

Most often, it is important that a date also near-precisely represent a point in time. In Swift, for that, we have Foundation.Date. TimeIndependentDate fills a gap where, in limited circumstances, we need to deal with a date independent of time. This is particularly useful when interfacing with third party systems which supply dates independent of time.

I often find myself needing a time-independent date in Swift. So I've open-sourced a TimeIndependentDate type for anyone else that might need one: https://github.com/hwjeremy/time-independent-date-swift

Example Usage

// Initialise a date, throwing a `TimeIndependentDate` error if the supplied
// literal values are invalid.
let timeIndependentDate = try TimeIndependentDate(
    year: 2020,
    month: .january,
    day: 1
)

// Parse a date from a string. Adjust encoding order as desired. A
// `TimeIndependentDateError` is thrown if the supplied string
// is not a valid date.
let timeIndependentDate = try TimeIndependentDate.from(
    "2021-01-01",
    encodingOrder: .dayFirst
)

iOS from zero to App Store at Procuret

Hugh Jeremy — Sun, 28 May 2023 21:03:41 +0000

Procuret is a business-to-business payments platform. Like many fintech startups, we bootstrapped with a web app. Web apps offer near-instant deployment, tight iteration loops, and a permission-less development environment. Perfect for finding product-market-fit.

Native iOS apps offer great accessibility, blazing performance, and a type-safe development environment. They are ideal for offering a higher quality experience when product-market-fit has been achieved. Given Procuret's growth, it is natural for us to move focus from web to native.

I got started writing apps in SwiftUI when it was first released. It was not production ready. Four years has made a huge difference. SwiftUI is now in a great spot. We found almost everything just works.

One senior (myself) and one junior (Kayla Hoyet) worked on the app. Combined we spent about 6 months "full-time-equivalent" to build it, spread out over one calendar year. We wrote 24,000 lines of code.

Of that, 8,000 lines is the open-source API library. Take a look to see how we structure our data.

We were thrilled to discover how easy it is to deploy to iPad as well as iPhone. The iOS app for both platforms is a single build.

At runtime, we query the horizontalSideClass to determine how much data to display. The Instalment Schedule is a great example. In the screenshot below, note that we display their bare minimum amount of data for iPhone, but robust data on iPad.

With 20/20 hindsight, I wish we had trusted NavigationPath from the start. It was introduced in iOS 16 and works very well. Initially I was wary of it, but we adopted it aggressively late in the development cycle.

// A very common pattern that `NavigationPath` makes easy:
// Popping back to the root view from deep in a `NavigationStack`.

@State var navigationPath: Array<Destination> = []
@State var shouldPopBackToRootView: Bool = false

// later on...

.onChange(of: self.shouldPopBackToRootView) { newValue in
    if newValue == true { self.navigationPath = [] }
}

We found the App Store Review process navigable, fast, and clear. Our Test Flight builds were typically approved within 18 hours. App Store approval came within 36 hours.

SwiftUI is very good. It puts native app deployment within reach for small teams. It is fast to write, resistant to bugs, and a pleasant working environment for the developer.

If you have questions about iOS app development, ask here in the comments or @hugh_jeremy on Twitter. Check out Procuret on the App Store to access our flexible payment options. It is available to businesses in Australia and New Zealand.

Apprenticeships in software development

Hugh Jeremy — Mon, 19 Oct 2020 07:08:27 +0000

Here in Australia, if I want to be a sparky, chippy, bricky, or dunny diver, I would start out as an apprentice. As a first year apprentice electrician I would get paid about $40k AUD per year to work and learn on the job.

If I stuck with my learning, I would be looking at an average of about $85k per year, and well north of $130k if I gunned it into senior electron-pushing.

Apprenticeships mean mentorship, training, pathways and practical experience. They exist in society because they are great way to turn fresh-faced kids into seasoned professionals in a safe, fair manner.

So where are all the software developer apprenticeships? If I search for "apprentice software developer", I get:

advertisements for bootcamps
"entry" level jobs requiring "previous XX experience"
aggregator listings for trainee jobs in non-software fields

When I started out writing, I had zero knowledge and an extreme propensity to stick my typing fingers in the proverbial wall socket, just to see what would happen. Fortunately I had some great mentors around me to nudge me towards good practice.

Now I get to build entire tech stacks for startups. How did I pull that off? How do I help more people pull the same trick? I'm not sure, but it sure didn't involve bootcamps or applying to trainee jobs demanding "3+ years in PHP/Wordpress". I'd like to...

Pay forward the help I received
Spark discussion about apprenticeships in programming

So, I've posted my ~~first job ad for an apprentice~~ (please note - applications for this position are now closed). If like me you are fortunate enough to have risen from the fresh-faced to the battle-hardened ranks of keyboard-warriors, I encourage you to do the same.

Guiding principles for a new engineering team

Hugh Jeremy — Sat, 10 Oct 2020 22:25:45 +0000

What principles should guide engineering decisions? At Procuret we are starting to scale up. It's time for us to grow our engineering team. I want to ensure that we can do so while retaining a principled engineering culture.

To that end, I've drafted up the following principles.

1. User data are sacrosanct

Anyone that interacts with our software provides us with data. These data might be deeply and obviously personal, like identity documents. They might be less obvious personal, like browser data, approximate location, or usage patterns.

All of these data are sacrosanct. Protecting these data from inappropriate access, by parties internal or external, with intentions malcious or careless, are our primary concern at all times.

2. There is no such thing as "User error"

There's an old joke that some errors have the code PEBKAC: Problem Exists Between Keyboard and Chair. While funny, if used in seriousness such a joke reveals a dangerous arrogance. If someone using our software is confused, we have done something wrong. Our software is the problem.

3. Speed is quality

How often do we release updates, how fast do we build new features, how quickly does our test suite run, how rapidly do we fix reported bugs, and how short is our page load time on customer devices?

The faster we can do these and other things is a measure of our performance. What we do in a day is less important than how fast we do it.

4. There are no stupid questions

If you don't understand what someone else is saying, there is a very strong chance they don't understand either. Ask questions for your sake and the sake of everyone around you.

5. Readable code is good code

Our code should be at least somewhat comprehensible to non-technical observers. Declarative, natural language code is fast, maintainable code.

--//--

What do you think? Have I got it right? What would you add or change?

Practical applications of protocols in Python

Hugh Jeremy — Wed, 24 Jun 2020 03:54:15 +0000

There's no such thing as a free lunch. In object-oriented code, protocols offer a very close approximation. In this context, a protocol is a set of behaviours that, if exhibited by a type, guarantee certain other behaviours.

For example, consider a hypothetical class, Human:

class Human:

    def __init__(
        self,
        name: str,
        unique_id: int
    ) -> None:

        self.name = name
        self.unique_id = unique_id
        return

    @classmethod
    def decode(cls: Type[H], data: Any) -> H:
        return cls(
            name=data['name'],
            unique_id=data['unique_id']
        )

This class has an initialiser and a single class method, which we will assume is used to decode deserialised representations of Humans. For example, when they are retrieved from a database.

Suppose we want to be able to decode many Human instances at once. Perhaps our database returns lists of Human. We could add a new class method:

# continues `Human` definition from above

    @classmethod
    def decode_many(cls: Type[H], data: Any) -> List[H]:
        return [cls.decode(h) for h in data]

Easy enough. We can now call Human.decode() on single instances, and Human.decode_many() on lists.

Consider that nothing in the .decode_many() function body depends on the actual implementation of Human. The .decode() method is completely opaque to .decode_many(), and .decode_many() does not need to be aware of the .decode() implementation in order to do its job perfectly.

With that in mind, consider a second class, Email. Suppose it is defined as follows:

class Email:

    def __init__(
        self,
        body: str,
        confirmed: bool
    ) -> None:
        self.body = body
        self.confirmed = confirmed
        return

    @classmethod
    def decode(cls: Type[E], data: Any) -> E:
        return cls(
            body=data['body'],
            confirmed=data['confirmed']
        )

    @classmethod
    def decode_many(cls: Type[E], data: Any) -> List[E]:
        return [cls.decode(e) for e in data]

It should be noticed that Email.decode_many() is identical to Human.decode_many(). We could write .decode_many() in a generic form as follows:

def decode_many(
    a: Type[ATypeWithDecodeMethod],
    b: Any
) -> ATypeWithDecodeMethod:
    return [a.decode(c) for c in b]

In english: "Take any type having a .decode() method, and call that method with all instances of data in this array of data, and return the resulting array"

Having a .decode() method is a behaviour which, if exhibited by a type, guarantees another behaviour: The ability to be fed to .decode_many(). We can use the word "protocol" to describe the requirement to have a .decode() method, and a class exhibiting that requirement is said to conform to the protocol.

We can write such a protocol like so:

class Decodable:

    @classmethod
    def decode(cls: Type[D], data: Any) -> D:
        raise NotImplementedError

    @classmethod
    def decode_many(cls: Type[D], data: Any) -> List[D]:
        return [cls.decode(d) for d in data]

Our original Human definition already has a .decode() method. As such, in practice, it already conforms to the Decodable protocol. We can identify is as conformant, such that it gains access to .decode_many():

class Human(Decodable):
    # definition remains otherwise unchanged from that
    # presented earlier in this article.

Now, we can call Human.decode_many() and receive a list of Human instances in return, despite the definition of Human not including any .decode_many() method. We can do the same with Email, such that we are not duplicating code.

A Note on Formality

This is a good time to pause consider the elephant in the room: What makes a "protocol" different from regular old class inheritance? There's no formal definition of a protocol in Python, so how can Decodable be said to be a protocol?

The answer is that in this context, a "protocol" is what you as the programmer define it to be, in your own mind. It just so happens that Python's class keyword provides the behaviours necessary to implement protocol relationships in Python code.

Some languages give explicit protocol tools: Swift has protocol, Java has abstract, and C# has interface. Each one differs in nuanced ways, but all seek to identify code which defines behaviours that, if exhibited by a type, guarantee certain other behaviours.

A key to the effectiveness of protocols in Python is that the protocol should not have an initialiser. Any class adopting a protocol should be able to do so while retaining full responsibility for and control over its own initialisation.

Just like static type checking, property immutability, or any other Python paradigm, it is up to you whether you want to obey the rules you define for your protocols.

Extending protocols

True joy arrives when we decide we want Decodable objects to be able to do more stuff. Any new capabilities we add to the Decodable protocol that do not change the protocol requirements are essentially free.

For example, suppose that our database may return optional data. That is, in response to a query we may receive some data or we may receive None. Our .decode() method definition does not make such allowances. If it is fed None it will crash.

We can add a new method like so:

# Continues the `Decodable` definition from above
    @classmethod
    def optionally_decode(cls: Type[D], data: Any) -> Optional[D]:
        if data is None:
            return None
        return cls.decode(data)

Now both Human and Email may be optionally decoded, and we did not even have to touch their definitions. Let's go even further. Suppose we want to be able to load Human and Email from raw JSON-serialised data:

# Continues the `Decodable` definition from above
    @classmethod
    def deserialise(cls: Type[D], serial: str) -> D:
        return cls.decode(json.loads(serial))

Again, without touching Email or Human, we have added new capabilities to both. Not quite a free lunch, but so easy that we could call it one.

Versioning a Relational Data Model

Hugh Jeremy — Wed, 17 Jun 2020 08:31:57 +0000

Suppose we have an application dealing in Birds. We have a Bird class, which could be in any language, but which we'll consider in Python for examples sake.

class Bird:
    def __init__(
        self,
        unique_id: int,
        species: Species, # Assume defined elsewhere
        name: str,
    ) -> None:
        self.unique_id = unique_id
        self.species = species
        self.name = name
        return

Inside our database, we might have created a birds table. Example SQL in this article will use Postgres syntax, but is mostly generic SQL.

create table birds (
    unique_id serial primary key,
    species integer not null references species(unique_id),
    name text not null
);

Suppose our application is terribly useful and popular, and many customers are very happy being able to uniquely identify and name their birds. However, some greedy, ungrateful customers would like to be able to rename their birds.

Inside the application, we might add a new method to our Bird class:

# Continues on from `Bird` defined earlier

    def rename(
        self,
        new_name: str,
        database: Database # Some database adapter type
    ) -> Self: 

        # Execute a database query changing the bird's name
        # and return the updated bird

Inside the database, we make the following changes:

create table names (
    bird integer not null references birds(unique_id),
    name text not null,
    created timestamp with time zone not null,
    primary key(bird, created)
);

insert into names (bird, name, created)
select
    unique_id,
    name,
    now() at time zone 'utc'
from   birds;

alter table birds drop column name;

Fantastic! We now have 5ish Normal Form renaming of birds. Everything is wonderful. Except... Some things are now pear shaped.

Our database is now incompatible with prior versions of our application code
We must ensure that any new database instance created for the bird application uses the newer data model

In a very small system like this one, these problems are not really problems. It's easy to keep track of what database instance is using what data model, and make manual adjustments where necessary.

What about when we have thousands of tables spread across dozens of schemas? These problems become very big problems.

It's easy to keep application code versioned using Git. Could we do something similar for a relational data model? Yes indeed. The first step is to make the database "self-aware". We can do this by creating a new table:

create table meta_revisions (
    executed timestamp with time zone not null,
    version integer not null unique
);

Whenever we modify the data model, we write to this table. Every revision gets an associated version number. For example, the revision that created the initial birds table might be 1 and the revision adding the names table might be 2.

You could put all your revisions in a folder, and then name each revision file with its version.

/project/data_model_revisions/1.sql
/project/data_model_revisions/2.sql

Git will naturally handle the process of versioning these files. So long as you never go back and edit a revision file, the folder becomes a sequence of instructions that can build up your data model from scratch. Almost like an SQL dump file, except one that takes the meandering course of your application's development.

I like to include a little tool in my codebases that handles data model revisions. In pseudo code, it goes something like this:

last_executed_revision = database.retrieve_last_revision();
sequence_number = integer(last_executed_revision)

for file in revisions_folder:
    file_sequence = integer(file.name_without_extension)
    if file_sequence > last_executed_revision:
        for statement in file.body.split(';'):
            database.execute(statement)
        database.record_revision(file_sequence)

Of course, in the real world, you can make this tool much more complicated and useful. It can automatically handle rollbacks on errors, do tricky query formatting, or some other task that eases management of your data model.

However you do it, the end result is data model bliss. You can always be sure that your database schemas are in sync with your application code, and you can rebuild schemas to the specification of any prior version of your application code.

Adding a Unified `NSToolbar` to a SwiftUI window

Hugh Jeremy — Mon, 30 Mar 2020 00:20:19 +0000

Previously on "Adventures in SwiftUI", I discussed adding an NSTableView to a SwiftUI project. I received a follow up question from Axel:

// Detect dark theme var iframe = document.getElementById('tweet-1244403543584526341-853'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1244403543584526341&theme=dark" }

To be honest, I don't have the faintest idea how I did this. So, I'll dig through the code and blog the process. That way, if anyone else has the same question, Google will hopefully land them here.

First stop, where do we create the NSWindow?

@NSApplicationMain
class AppDelegate: NSObject, NSApplicationDelegate {

    var window: NSWindow!


    func applicationDidFinishLaunching(_ aNotification: Notification) {
    // Snip

It's declared in the AppDelegate. I can't recall if all SwiftUI apps depend on the AppDelegate pattern... If yours does not, then the following is probably still useful, but you will likely need to adapt to your circumstances.

Here is the point of NSWindow creation:

// Enclosing code snipped
window = NSWindow(
    contentRect: NSRect(x: 0, y: 0, width: 640, height: 480),
    styleMask: [
        .titled,
        .unifiedTitleAndToolbar,
        .closable,
        .miniaturizable,
        .resizable,
        .fullSizeContentView
    ],
    backing: .buffered,
    defer: false
)
window.center()
window.title = "Draft Sport"
window.titleVisibility = .hidden
window.setFrameAutosaveName("Draft Sport")
window.contentView = NSHostingView(rootView: contentView)

The key thing to note here is the provision of the .unifiedTitleAndToolbar mask in the style mask array.

Next, we need to create the actual toolbar content.

// Enclosing code snipped
let toolbarButtons = NSHostingView(rootView: ToolbarButtons())
toolbarButtons.frame.size = toolbarButtons.fittingSize

let titlebarAccessory = NSTitlebarAccessoryViewController()
titlebarAccessory.view = toolbarButtons
titlebarAccessory.layoutAttribute = .trailing

Finally, we add the titlebarAccessory to the NSWindow instance:

// Enclosing code snipped
window.toolbar = NSToolbar()
window.addTitlebarAccessoryViewController(titlebarAccessory)

And voila, you've got a unified toolbar. Watch out though: I haven't gone any further with this. I imagine there are going to be all sorts of challenges developing the typical behaviour expected of a unified toolbar.

I hope this helps you Axel, and anyone else enjoying SwiftUI!

Hugh

Adding an NSTableView to a SwiftUI View

Hugh Jeremy — Wed, 18 Mar 2020 22:38:52 +0000

SwiftUI made a surprisingly good first impression. Of course, things get more complicated as soon as you want to build something actually useful. Tables are a fundamental part of many macOS applications. How can we build them in SwiftUI?

Apple pushes the SwiftUI List pretty hard. It's great for iPhone GUIs. It is woefully inadequate for the desktop. Compared to the old AppKit NSTableView it is a children's toy.

You can certainly build tables out of List, using rows of HStack views. My test case was the Draft Rugby Player Stats table. Using draft-sport-swift to source the data, List gave me something approaching serviceability:

In code, it's not pretty. Lots of manual column-width calculation. Manual row banding. Manual row formulation in a dedicated row view. In the end, it involved writing lots of code to get something that approximated the aesthetic of an NSTableView, but without all the functionality that NSTableView includes.

Creating an NSTableView also involves writing lots of code. However, you get a lot of bang for your buck. Ideally, we could slap an NSTableView straight into our SwiftUI app. Fortunately, we can!

Step 1: Create `NSViewController` / `NSTableView` as normal

import Foundation
import AppKit

class PlayerNSTableView: NSTableView {
    // Define your NSTableView subclass as you would in an AppKit app
}

class class PlayerNSTableController: NSViewController {
    // Define your NSViewController subclass as you would in an AppKit app
}

Step 2: Create an `NSViewControllerRepresentable` wrapper

SwiftUI is all about View implementations. AppKit is all about NSViewController, NSView, the relationships between them, and a bunch of other crap. NSViewControllerRepresentable is the bridge between the AppKit and SwiftUI worlds. It is itself a View conforming protocol, and can be passed around in SwiftUI like any other View struct.

Create a struct conforming to NSViewControllerRepresentable, and add the required protocol stubs. Observe the tangled mess that results:

import Foundation
import AppKit
import SwiftUI
import DraftSport

struct PlayerNSTable: NSViewControllerRepresentable {

    @Binding var players: Array<Player>?

    typealias NSViewControllerType = PlayerNSTableController

    func makeNSViewController(
        context: NSViewControllerRepresentableContext<PlayerNSTable>
    ) -> PlayerNSTableController {
        return PlayerNSTableController()
    }

    func updateNSViewController(
        _ nsViewController: PlayerNSTableController,
        context: NSViewControllerRepresentableContext<PlayerNSTable>
    ) {

        if let players = players {
            nsViewController.refresh(players)
        }

        return

    }

}

There's a lot to unpack here. Never fear, the only bit you really need to care about is the body of makeNSViewController(). Inside the body, you will see return PlayerNSTableController(). That's the key: Initialise the NSViewController subclass you defined in Step 1.

Step 3: Manipulate the wrapped `NSViewController` from SwiftUI

We're obviously going to want to manipulate the AppKit table data from SwiftUI. In the above NSViewControllerRepresentable implementation, you will notice the line @Binding var players: Array<Player>?. This is a bridge passing data between the SwiftUI and AppKit worlds.

Like any other struct conforming to View, PlayerNSTable may observe changes to its properties and update the GUI in response. The magic sauce is the @Binding decorator. Now, when .players is changed, the .updateNSViewController() method of our NSViewControllerRepresentable is called.

Inside .updateNSViewController() we can do whatever we like. I happen to expose a .refresh(:Array<Player>) method on my PlayerNSTableController, which ultimately calls .reloadData() on the underlying NSTableView. It's up to you how you want to feed new data into your NSViewController / NSTableView pair.

Step 4: Add your wrapped AppKit view to a SwiftUI view

You can now add your NSViewControllerRepresentable implementation to any SwiftUI View. Here's my implementation, PlayerNSTable, being added to an enclosing View:

import SwiftUI
import DraftSport

struct PlayerTable: View {

    @State var players: Array<Player>? = nil

    var body: some View {
        PlayerNSTable(
            players: self.$players
        )
            .frame(alignment: .topLeading)
            .onAppear(perform: retrievePlayers)
    }

    func retrievePlayers() -> Void {
        self.players = nil
        Player.retrieveMany(
            season: Season(publicId: "2020")
        ) { (error, players) in
            guard let players = players else {
                fatalError("No players")
            }
            self.players = players
        }
    }
}

Note that when PlayerNSTable appears, Player data are retrieved via the retrievePlayers() method. As with any other SwiftUI View, changes to @State decorated properties are observed. When Player.retrieveMany() executes its callback closure, the .players property is updated. This update ultimately triggers the updateNSViewController() method we discussed in Step 2.

The end result:

A fully functional NSTableView inside a SwiftUI View hierarchy. Phew! That was intense. If you have any questions, find me @hugh_jeremy on Twitter.

SwiftUI first impressions / pain analysis

Hugh Jeremy — Wed, 18 Mar 2020 22:38:49 +0000

For years I've been occasionally dabbling in macOS native application development, and for years I've been resisting the urge to throw my MacBook out the window. Any delusions I've occasionally had about releasing native macOS apps have been flattened by the AppKit pain train.

Where's my Delegate? Or was it the Controller, Model, or View that I needed? Was it in my Storyboard? Xib? Nib? Jib? Why is Xcode crashing? What is this non-deterministic compiler error?

I can see how a dedicated developer could become a weapon with AppKit, but if you're multi-disciplinary the time input/reward ratio is just way off.

Apple has presumably realised this, hence the new kid on the block: SwiftUI. I'd heard about this new-fangled "SwiftUI". It was only this week that my urge to self-flaggellate was strong enough to try it. So I fired up Xcode, and...

Well. What a pleasant surprise. Everything, and I mean the whole damn production, is boiled down into one glorious concept: The View.

This rustles my jimmies in all the right directions. The only way I ever made any progress with AppKit was to ignore its psychotic smorgasbord of concepts and build self-contained NSView subclasses. Then, those subclasses could be composed into a UI.

That's effectively SwiftUI in a nutshell. You create View implementations, and then you add them to each other. That's it.

View is a protocol, not a class. No inheritance. You have full flexibility to initialise this bad boy however the hell you want. They're just fresh-off-the-stack structs with a .body property requirement.

Could it get better? Yes it could get better. Some people are imperative people. The want to tell you how to do something, rather than what they want done. These people have titles like "[insert JavaScript framework] Evangelist" and you should socially distance yourself from these people.

Better people are declarative people. They tell you what the objective is, and then leave you alone to achieve it. SwiftUI is a declarative person. The difference in code:

# Imperative Python
relevant_heights: List[int] = list()
for tree in forest:
    if tree.age == 4:
        relevant_heights.append(tree.height)
return sum(relevant_heights)

# Declarative Python
return sum([t.height for t in forest if t.age == 4])

In the first example, we told Python how to find the right tree heights. In the second example, we told Python what we wanted and let it work out the implementation details itself.

If you've ever worked in SQL, you will be familiar with the declarative style, because SQL is entirely declarative:

/* Declarative SQL */
select sum(height)
from   trees
where  age == 4

The declarative attitude is the one required to grok the following:

struct Header: View {

    var body: some View {
        VStack {
            Text("Top row text")
            Text("Bottom row text")
        }    
    }
}

We declare that we would like a vertical stack of views (VStack), inside of which we would like two pieces of text (Text).

When I first saw this, I was frustrated. Where exactly do we return from inside the VStack? And what is returned? How can two Text declarations magically turn into two lines of text?

Being an absolute SQL fanatic, I found peace by accepting that we are declaring what we want rather than how we want it done. Writing Swift code against the SwiftUI API is more like writing SQL than say, imperative AppKit code.

We can mix and match views willy-nilly. Say we declare an H1 view, which in our application will be roughly analogous to <h1> in HTML:

struct H1: View {

    let headingText: String

    var body: some View {
        Text(headingText).font(
            .system(
                size: 32,
                weight: .bold,
                design: .default
            )
        )
    }
}

We can now use H1 inside our earlier Header example:

struct Header: View {

    var body: some View {
        VStack {
            H1(headingText: "Top row text")
            Text("Bottom row text")
        }    
    }
}

Producing:

That really is it, kids. Everything else is a variation on the them of defining View implementations and composing them together. Nested hierarchies of View become your application user interface.

What a pleasant surprise. SwiftUI might be a keeper. Some quick summary thoughts:

Good

Everything above
Xcode doesn't crash constantly anymore
Swift package manager is great now

The Bad

Not many built in controls, re-using AppKit classes (e.g. NSTableView) quickly becomes necessary
AppKit / SwiftUI interaction is poorly documented
All the Apple docs are (surprise) focused on UIKit people, & iPhone GUI paradigms

Want to dive a little deeper? In a follow up, I discuss how to integrate an AppKit NSTableView into a SwiftUI View hierarchy.

Hugh

Mixing synchronous and asynchronous requests for serious speed

Hugh Jeremy — Sat, 14 Mar 2020 05:32:05 +0000

You know what I'm talking about. Those infuriating websites that present animated grey boxes while they fetch their content asynchronously. For seconds. No one has seconds. Give me the content now!

Draft Rugby is a fantasy Rugby app. It's in early development. Our main feature is the Player Stats page. This page is effectively a glorified table: It allows rapid search and sorting of the ~800 players in the Super Rugby season.

Before today, it loaded pretty quickly. Here's the process:

A browser makes a GET request to /player-stats
Draft Rugby replies with a bunch of HTML, CSS, and JS
The browser runs the JS, which includes an immediate GET request to /api/fantasy/player/list vis the Draft Sport JS library
Draft Rugby replies with a bunch of JSON
The browser eats the JSON and fills the player table

Step 3 is an asynchronous javascript request leading to document manipulation, commonly known as "AJAX". That's nice, because the user can now sort and search the table. Each time they do, more asynchronous requests are made to get them the data they want, and refill the table.

Except it's not always nice, because of the speed of light. In an ideal case, with a client device say, 30 kilometres from the datacenter, there might be 50 milliseconds between the start of step 1 and the start of step 3. In Draft Sport's case it was taking a whopping ~270ms to finish the whole sequence and begin animating the table.

No one has time for 270ms! A user will notice this delay, without question. And it get worse: Your user's visual processing system needs to parse your fancy loading animation while the async request is happening. Then it needs to dump that information and re-parse the actual page content.

Don't do this! It sucks! Let's shift the initial table load back onto the server. Now the sequence looks like this:

A browser makes a GET request to /player-stats
Draft Rugby replies with a bunch of HTML, CSS, and JS, including the content of the player stats table retrieved via Draft Sport Py.
The browser paints everything

From 5 steps to 3. Now:

No double round-trip to the datacenter to fetch the initial data
No loading animations for the user to parse

What's the tradeoff? It depends on the disposition of your API. Draft Sport API is not the fastest thing in the world, yet - It takes about 50ms to retrieve the player table. That request now blocks the time-to-first-byte, slowing the page delivery down by 50ms.

The synchronous result is still way better. The time until content is fully presented drops from about ~450ms to ~200ms. As Draft Sport API matures and gets faster, that time will drop further, whereas the speed of light isn't going anywhere. And in the real world, your user is not going to be 20ms from your datacenter. The further away they are, faster the synchronous request becomes. Your framework can't outrun the speed of light!

Conclusion? Don't be afraid to hold up returning your first byte with a server-side API request. If you know what data the client wants, your overall time to displayed content will probably be significantly lower than if you return it asynchronously via an AJAX request.

-Hugh

Cognition-oriented Programming

Hugh Jeremy — Mon, 02 Dec 2019 21:17:51 +0000

Programming is addictive. As programmers we have immense power. We can create machines of practically unlimited scale and scope. Our creations may yield immense joy and utility. In code anything seems possible.

We programmers are still human. We are delicate, non-deterministic machines with squishy bodies and even squishier minds. Our capacity to build software is a function of our capacity to direct the limited resources of our bodies and minds.

Programming paradigms provide loose rulesets to help us direct those resources. We adopt functional-oriented, object-oriented, data-oriented, or some other programming orientation. These paradigms are well established and serve wonderfully.

They are top-level distinctions that sit on top of a huge stack of programming techniques, patterns, fads, and principles. Much joy comes from exploring new ways to write code, and finding out what allows each of us to most effectively reach our goals.

Science gets us some of the way

What should drive that exploration? How can we know whether we should adopt a data-oriented approach to our latest project? The decision is often made out to be one of computer science. What paradigm best fits the requirements of the system?

A game programmer might generally require their program to respond to user input in 16 milliseconds or less. They might be well served in trading some readability for intensely optimised hot-loops that keep as much data in L1 cache as possible. Perhaps data-oriented C++?

A web programmer might have bit more room to move, client-side progress animations and common acceptance of network latency yielding an acceptable response time of 20 - 150 milliseconds. They might be well served optimising for readability. Perhaps object-oriented Ruby?

Yet the choice is rarely so clear cut. The latest fads, frameworks, and celebrity-programmer proclamations might influence us in different directions.

Think first, paradigm later

Our guide should be the disposition of our own cognition. Each of us has a different mind. Your brain has developed differently to mine. Different experiences, training, and genetic-predispositions conspire to influence the manner in which we reason about code.

This is quite abstract. Let us examine a practical example. Consider a single class definition. How long is too long? 200 lines? 1,000 lines? What if we mix multiple classes into a single file?

You might be comfortable working with files thousands of lines long. Having witnessed such capability, I initially worked in this manner as well. Over many years I realised that I was not capable of maintaining a mental map of so much data. Now, I aim for a maximum of 150 lines per file, with strictly one class definition per file.

If a definition becomes longer than 150 lines, I actively ponder breaking it into smaller composable parts. As I move through my programs, I operate on a maximum of two files at a time, working on the flow of data from to another. In this way, I am always operating on a maximum of approximately 300 lines of code.

To you, this might sound absurd. You might have huge files and be perfectly comfortable surfing through them. This is exactly the point: We are all different, and we must seek to write code in a manner that supports our own cognition. Call it “cognition-oriented programming”.

Cognition for Teams

In a team, this might appear to present problems. What if your CTO likes massive files and you don’t? I suggest that in a well-gel’d team, leadership is setting objectives and standards, not methods.

That is, you are ideally told what you need to do and the bounds within which you need to do it, not how to do it. In such an environment, you might adopt a team-wide code-style guide. You might have rules such as “no global variables” and “no mutable state”.

Then, within these bounds, you might focus on providing maintainable, reasonable, and clear public interfaces for your code. Behind those interfaces, and while always maintaining compliance with the set bounds, you may lean towards optimising for your own cognition.

Your Optimised Mental Model

The concept of being “in flow” is well studied. Cognition-oriented programming might be viewed as a subset of the requirements for being “in flow”. At the highest level, it may be viewed as the search for your own hyper-optimised mental model.

Your brain has some strict finite limits. Your short-term working memory is likely limited to storing around seven “objects” at once. Your long-term memory might store pointers to every corner of your 200,000 line program, but at any instant, you can only reason with reference to some small subset of that code.

How you structure that limited reference is crucial. Think of your working memory as your own L1 cache. In paradise, your program is crunching cache data at warp speed, never needing to reach out to comparatively glacial RAM. In maximum flow, your mind is crunching on concepts stored in your working memory set. You reason about them at immense speed and with great precision.

In reality, our real programs need to go to RAM. Worse, they might need to access persistent storage. Heaven-forbid they need to take the long voyage out through the network stack. This is true for our mental models as well. In our metaphor, RAM might be some other piece of our codebase. Storage might be referencing some documentation. Network I/O might be talking to another human being.

All of those operations are crucial and important. Optimising them will yield more time in nirvana, with your optimised mental model facilitating a flow of performant, reliable, and reasonable code. The feeling, in my experience, is close to that of playing a musical instrument. The dance of fingers across the keys is unending, rhythmic, and perhaps even spiritual.

Seek Nirvana

Finding your cognition-oriented model takes time. Try new patterns. Read widely. Observe what works for some very successful programmers. Not because you should imitate them, but because their models might provide inspiration for some part of your own.

Engage in trial and error. Construct, destruct, and modify systems. All the while, observe yourself. Do you feel transcendent? Or do you feel as though you are straining to keep a grip on the program? Do you instantly see the path to a new feature, fixed bug, or performance improvement? Or do you strain to comprehend how to proceed?

These questions will enable you to find the patterns that map to your own cognition. Do not force your patterns on others. Do not presume others’ patterns will work for you. Code is the tool that enables you, as a squishy mammal, to dent the universe. Seek to make it your own.

Feedback for junior developers

Hugh Jeremy — Wed, 29 May 2019 21:09:31 +0000

When I was younger and dumber, I charged pretty hard. Sometimes I would upset people by pushing too hard for an end result. I didn't consider how my actions would affect people around me. Back then the damage I did was usually a small, though still unacceptable, as I was junior cog in the machine.

These days, I am in senior positions with responsibility for the output of junior developers. The team's collective output depends on everyone having high morale and the confidence to take risks, make mistakes, and learn continuously.

Young Hugh's hard-charging ways weren't acceptable then, and they would be devastating if applied from a senior position.

Of course, I often copped it as good as I gave it. I have painful memories of senior people shitting on my best efforts. It's an awful feeling to have tried hard to find a creative solution to a problem, only to be brutally shut down by someone in a position of power.

This effect is amplified by people's relative tolerance for feedback. Some people have high self-confidence, and are generally better able to recover from the morale hit of harsh feedback. Others are gentler souls, very sensitive to criticism and vulnerable to retreating from creative development in the face of harsh feedback.

You won't necessarily know who's who. Some of your developers might look like they can roll with the punches, but are quietly de-motivated to work with you. Personally I think I give off a confident persona: I will get up on stage to give a speech, post stupid videos, and put my hand up first to take on a big challenge. Yet I have cried openly in front of colleagues, on multiple occasions.

Conclusion: We should take great care in how we offer feedback to our colleagues. In particular, junior developers who are at a formative stage in their code-crushing adventure. I don't have an all-conquering strategy about how to best give feedback.

To provoke discussion, I present an email I sent earlier today. The content is esoteric to the particular project, so we'll have to ignore that and instead focus on the style of the feedback. How does this make the recipient feel?

Hi [Junior Colleague]!

I’ve made some adjustments to the FAQ page, and I’ve got some feedback on your code. This is not because you did anything wrong. You did great! Instead, it’s about me applying a consistent set of code rules to the [App] codebase, that allow me to keep the whole thing straight in my head.

What I’m doing here is not necessarily better or worse than what you did. Instead, it’s just my style. Because I need to maintain responsibility for the whole app, I need to enforce my style or I my mental map of the whole app can break down.

Moral of the story: Do what you need to do to get the job done. Sometimes I might come in with feedback like this, but it’s not because you did anything wrong. In fact, you did right because you got the required feature working! I will always be thrilled when you add functionality, regardless of whether or not it adheres to these rules.

CSS Namespacing

Good job creating accordion.css. I’ve plopped it in shared/accordian.css simply for organisational purposes. Inside, ensure all your classes are namespaced: .accordion-active instead of .active, .accordian-panel instead of .panel. Doing so means we never have to worry about conflicts between different stylesheets, we can mix and match them safely. You did this for almost all the classes, nice work!

Inline Javascript

Ensure all Javascript is added via the View superclass, rather than inline in an HTML template. I’ve moved things into a scripts/other/faq.js script and classes/shared/accordian.js class. The View superclass does a whole bunch of Javascript management, and it can’t work its magic if Javascript is inline in an HTML template.

Javascript Variables

Never use var - It puts the variable in global scope. Using let and const means that we can safely mix and match classes and scripts without them ever stepping on each others toes. Generally everything should be const unless there is an extremely compelling reason to use a let.

Javascript Objects

Err on the side of object-oriented code, rather than procedural code. Procedural code is generally identifiable as a series of steps manipulating low-level datatypes like DOM elements and strings. Object oriented code usually (if done well!) looks a little more like English, with phrases composed of high-level types like ‘Accordian’.

Generating object-oriented code might involve creating a mental map of the nouns you want in play, and the verbs that will act on those nouns. Nouns become classes and verbs become methods.

E.g. “I want to toggle the open state of a bunch of accordions”. Our key noun is “accordian”: That will become our class. It has an open state that it will stored as an internally/private property. The key verb is is “toggle”: That will become our class method. Because we want a “bunch” of them, we will create a static class method that allows us to build a collection of Accordians.

This means you can compose code that sounds more like English, e.g. “accordian.toggle();” or “const accordions = Accordian.fromElementsWithClassName(’accordian');". I find this easier to maintain when I inevitably come to look at it again months later.

Doesn’t make any sense? Don’t fret! I’m not necessarily a very good teacher! You can see how your accordian code was translated by looking at classes/shared/accordian.js. Please feel free to charge some time to [Client] while looking through this stuff. Learning is part of the job!

Conclusion

You did nothing wrong, and everything right. This is all about the personal style I’m enforcing so I can execute my responsibility to advance the entire application. Other developers will have other styles, you will have your own style. I will always be thrilled with you create new functionality, regardless of what style you use.

Cheers

Hugh

How was that? What would you change? I think this email follows a few feedback patterns:

Acknowledge successes
Encourage future experimentation
Give reasoning behind desired changes
Provide helpful hints for gaining knowledge

These patterns are self developed, and self identified. I wonder if you know of any great guides on how to give good feedback. Do you have any stories you can share about when giving or receiving feedback went well, or badly?