Bad APIs

I write a lot of C++ code at my day job, so often I don’t want to do that for my hobby projects. There’s a lot of complexity in C++, no doubt. However, I think many of troubles of C++ are simply bad API designs.

As just an example, let’s look at the std::map API. I mean, really?

OK… so there are some things we know about a map, but the most important is that the key values are unique. That is, if “name” exists, there will be one and only one of them.

So what the flip is up with the iterator stuff? And why on earth is there a count() function instead of just a contains() function?

I’m sure there is some explanation for it, but I’m not terribly interested in it. As a consumer of the API, I don’t really care why you make my life more challenging. I want to work with nice, clean APIs.

Swift vs. C++

Part of what make Swift look more appealing is the clean syntax and sometimes better (though, there are many examples where this isn’t the case today) API interfaces. Let’s take a look at a snippet of a Vapor project I’m toying around with:

That’s some pretty reasonable code. Maybe I’d change a few things, but there’s nothing that makes me go, “what the heck is wrong with you?”

Compare that to what it might look like in straight up C++:

I mean… it’s not that terrible, but there is a lot of WTF? in there. The biggest problem is that these APIs cause the code to really switch context from the get() handling to the details of parsing out data. That’s not cool.

Better APIs

We can fix this though and create something that is much more easier to follow and use:

This would be the same exact number of lines of code as the Swift version if I change the Swift version to not throw on an error trying to get the parameter. But more importantly, we didn’t lose anything in the C++ version. However, we did gain code that is much easier to read and maintain.

Build better APIs, your code and coworkers will thank you for it.

Bad APIs

Extensions and Categories

There’s a lot of talk about how extensions are used for code organization. This is even one of the primary defenses for some of the Swift proposals. However, it’s missing a key component of organization: categorization.

If you remember when dinosaurs roamed the Earth, they wrote code to maneuver their space ships with a language that must have been from aliens: Objective-C.

If you wanted to extend a type and provide yourself some new goodies, you would do so like this:

@implementation Raptor (BirdOfPrey)
// new cool stuff here

In Swift, however, it’s not as clear what we should do.


Ok, this is the easiest and most straight-forward way do it. It’s close to what we had before. But as a comment, it has a bit of disconnect from the type. If you’re like me, you’ve also trained yourself to skim over comments like ads on a website.

extension Raptor /* BirdOfPrey */ {
    // new cool stuff here


Now, of course, I think the most illustrious Swifters would say, “Obvious: use a protocol.”

Yep, you could do that:

protocol BirdOfPrey {}
extension Raptor: BirdOfPrey { /* ... */ }

And that’s not too bad, but you’ll implement it one of two ways:

  1. An empty protocol as you simply don’t care about duplicating the signatures for a one-off categorization mechanism.
  2. A full on protocol, because you’re a good little dinosaur offspring!

However, unless you’re going to be reusing these protocols, both are simply noise that you’re adding to the system that is supposed to simply help you organize your code.


Another approach that was mentioned on Twitter:

Honestly, I’d not thought of this approach.

typealias RaptorBirdOfPrey = Raptor
extension RaptorBirdOfPrey {
    // new cool stuff here

I’m not personally a fan of this as it confuses the type some and introduces just as much noise as the empty protocol, but with more downsides, in my opinion.

Do Nothing

Of course, this is also an option too. Simply do nothing. Sadly for my code, this is often what I end up doing.

Wait A Minute…

I know what some of you are thinking… didn’t we have to define these categories in a .h file so we could use them?

Yes. If you wanted to use them outside of the file, that’s 100% correct. Thanks C.

But! Swift doesn’t have header files so we should not have to be burdened with all this duplicate declaration stuff… but, in this case, we still kind of are if we want to go the protocol route.

It would be great if we could just do this:

extension Raptor (BirdOfPrey) {
    // new cool stuff in our implicit protocol: BirdOfPrey


Extensions and Categories

There are levels of survival we are prepared to accept

Regarding the Mac Pro announcement and my current hobby endeavors.



There are levels of survival we are prepared to accept…

I’m not talking Hackintosh here, because, well, I don’t really want to mess with all that. What I am talking about is something much more abhorrent!


Yes… that is Visual Studio Code running on Windows 10 with Vapor running on the oh so lovely named Bash on Ubuntu on Windows or Bash on Windows Subsystem for Linux or Bash/WSL for short.

It’s not terribly pleasant, but it works.

Apple, please don’t let us down.

There are levels of survival we are prepared to accept

Band-Aids: Swift, fileprivate, and #169

A bit of a rant…

Well… I was pretty disappointed that proposal #159 – Fix Private Access Levels was voted down. But when #169 – Improve Interaction Between Private Declarations an Extensions was approved… seriously?

Why? Why another band-aid? Why another special case rule that I need to learn about? Why introduce more inconsistency in the language?

I just cannot get behind a change where I need to explain to someone why this won’t work:

Or why if you want to move an extension from one file to another, you need to change from “private” to “internal“.

See, access control is still deficient for proper modeling if we revert back to Swift v2’s model, but at least there were no special rules to consider.

“Well, you see, private only allows access to those private bits if you’re in the same file.”

“Oh, well, then what does fileprivate do?”

“Well… it allows you to access that from anywhere within the file.”

“Wait, so what’s the difference?”

“You see, private allows only the extensions to see, but not everything else like other types or free functions.”

“Oh, cool, so I’ll just use that to poke into the private stuff in this class I’m subclassing too…”

“Um, actually… you can’t do that.”

“I thought extensions…”

“Right, subclassing isn’t an extension.”

“Ok. So how do I make those private bits only available to my subclasses in this file and not the other functions and types?”

“You can’t.”

“Wait, what? So the private keyword only has this special meaning in the context of protocol extension?”


Good times.

P.S. Don’t forget about the already existing special case for private on internal types… 🙄


Band-Aids: Swift, fileprivate, and #169

My Thoughts on Server-Side Swift: Routing

The folks over at put out another high quality video, this time on Server-Side Swift: Routing. I like the high level goal they are going for, but I actually approach the problem differently.

To me, the key of setting up good architecture is leveraging what you are given while keeping the boundaries between the libraries or frameworks that you are using and your own code.

For example, I’m working on a server-side Swift project for D&D. The full conceptual flow looks like for the scenario of a user looking up a spell with a given name:

  1. User makes a GET request to /spells/burning-hands
  2. Vapor looks up the route and invokes the handler
  3. Handler does conversions and passes to my own SpellRouter.get() function
  4. This function handles the non-Vaporized data calling into my lookup code: Spell.lookup(name:)
  5. Above function returns an array of [Spell] items
  6. The [Spell] is converted into an SpellCard which serves as an abstract HTML representation
  7. That gets rendered into raw HTML
  8. The raw HTML makes it back to the Vapor route handler
  9. A Vapor Response is returned
  10. The user sees the HTML page

It looks like a lot of steps, but it has the following benefits:

  1. Each layer is agnostic of the layer below it. That is, my logic layer knows nothing about Vapor, HTML, or HTTP; it only knows how to perform spell lookups based on strongly-typed parameters, this case: name.
  2. The boiler plate is essentially nonexistent.
  3. It maintains flexibility without forcing a rigid structure. Swapping out Vapor for another web framework is a matter of writing the conversion functions.
  4. It scales well to multiple rendering needs.

Let’s go over some code to help make things more clear.

Server Hookup

drop.get("/spells", String.self) { req, name in
    SpellRouter.get(name: name).html

drop.get("/api/spells/", String.self) { req, name in
    SpellRouter.api(name: name).json

The variable drop is a Vapor Droplet instance. This code is in my main.swift file. A couple of things to note:

  1. I do not abstract the path (e.g. /spells) out somewhere else. The server is what needs to know about paths, so this is the level it should exist at.
  2. Vapor pulls out the first parameter as a String because of my usage of the second parameter in the get() function.
  3. In my case, there is very little conversion that I need to go from Vapor specifics to my own routing code, just handling the name retrieval, which is done above.

The only other Vapor specific items are the html and json extensions that I have on my own HtmlResponse and JsonResponse types that get() and api() return from the SpellRouter type.

They look like this:

extension HtmlResponse {
    var html: Response {
        return Response(status: .ok,
                       headers: ["Content-Type": "text/html"],
                          body: self.element.html)

extension JsonResponse {
    var json: Response {
        return Response(status: .ok,
                       headers: ["Content-Type": "text/json"], 
                          body: self.json)

The Response class is a Vapor type. But that’s it, the main.swift file here is the only place Vapor is referenced.

Spell Routing

For my routing, I implement the same get() and post() style APIs. This makes the translation process fairly straight forward.

The routing function looks a bit like this:

static func get(name: String) -> HtmlResponse {
    let translatedName = decode(name: name).lowercased()
    let spells = Spell.lookup(name: translatedName)
    if spells.count != 1 {
        return InvalidHtmlResponse(message: "No spells were found with the name: '\(name)'")

    let spell = spells[0]
    return SpellCard(spell: spell)

Basically, and incoming request might look like this: /spells/burning-hands. The decode() function converts the name from “burning-hands” to “burning hands”. Then I call into my spell DB via the lookup(name:) function. And in this case, I only return the first spell found via a SpellCard class that is an abstracted HTML view of the card. The api() function returns a SpellApi instead.

In the End

Anyhow, I prefer this approach over the enum-style approach that was described. For one, it makes handling different types of requests (GET and POST for example) at the same URL extremely easy. They’ll have to encode that data somehow into their enum to handle it.

I’m interested to see how they progress through the problem though to handle more of the necessary aspects.

My Thoughts on Server-Side Swift: Routing

Why No External Templates?

I was asked on Twitter:

Could you expand in why [Swiccup] versus a template language?

I gave a brief answer there, but I think it’s worth talking about a bit more. Many of the HTML templating languages out there are simply trying to solve the problem that crafting HTML in code (or crafting HTML in general) can be a real pain.

As an example, the desired output might be this:


You have the data structure of:

"repo": [
  { "name": "resque" },
  { "name": "hub" },
  { "name": "rip" }

Using HTML libraries in code are generally a huge pain. But if you can have a file that simply describes this as (in mustache):


Or in Leaf, maybe it looks like this:

#loop(repo, "name") {

This is so much easier to read, understand, maintain, and author than authoring this by hand which might look something like:

for repo in repos {

Of if you’re using a typical HTML library:

for repo in repos {

The templates are just better.

So what’s the problem?

The problem is that they still come at a cost. Maybe times we’re moving from a typed system to an untyped system, so typos are easy to have happen. Most of the time there are no tools to help ensure that the templates are actually structured properly. This makes everything a runtime validation check.

The other problem is that we are introducing another language to understand, and in many normal use cases, figure out the interop between the host and the templating language for custom formatting or serialization of data.

The question is then: is there some tradeoffs that we can make to get the majority of the benefits from both sides? That is, more type safety and language similarity without the horrendous code that we typically write when authoring our templates in code?

Yes, but you need a language that is “powerful” enough to be able to create mini-DSLs.

Instead of writing the #loop from above, we could do something like: { name in
  b |> name

Now we can leverage many of the benefits of using our compiled language while still getting the the vast majority of the benefits from our template system. The really awesome thing is that extensibility is already built in. If you need to format the name in a specific way, you just need to call your function. Depending on the template system you are using, this could actually be a fairly difficult and time consuming thing to get done.

So, why don’t I use external template? I find them redundant and don’t add much to solving the problem.

Why No External Templates?

Swiccup, Round 2

Just a follow up from my previous post: Swiccup.

Sidenote: Swiccup might be a bit of a dumb name… I was thinking about renaming it SwiftyML, but then I saw another project that is similar called SwifTML, so that might be too confusing…

As I mentioned previously, the first round was a bit of prototyping. I spent a bit more time on it today and have come up with a more flushed out implementation and a more streamlined approach, but it does make use of a couple of operators overloads, essentially creating a mini DSL (domain specific language).

Let’s compare, the original:

The new version:

There are a few differences:

  1. There are now two operators: |> and <|
  2. The signature of all of the tag constructs are now uniformed; this greatly reduces the codegen boilerplate and complexity of the system.
  3. String interpolation now works

The |> and <| operators

The |> operator is used to denote a child relationship between two different HtmlElement structs. The left hand side is the parent and the right hand side is the child. This can be a single entity or an array of children.

The <| operator is used to denote attributes that should be assigned to the HtmlElement to its left, hence the arrow pointing left. This allows either a dictionary to be merged into the attributes store for the element. Above is an example of both single entry dictionaries and multiple entry dictionaries being merged in.

Streamlined Method Signature

The signature for each tag is really nice now, it’s simply:

(_ attributes: [String:String] = [:]) -> HtmlElement

Before, I had a nasty mess of things as I was trying to figure out the best call site API feel. The other nice thing about this is that I only need a handful of operator overloads to handle all of the cases too.

String Interpolation

So yeah, to get string conversion to work properly, you need to implement four different protocols:

  1. ExpressibleByStringLiteral
  2. ExpressibleByUnicodeScalarLiteral
  3. ExpressibleByExtendedGraphemeClusterLiteral
  4. ExpressibleByStringInterpolation

Good times. Also, the ExpressibleByStringInterpolation one is a real doozy. It’s also marked as deprecated, but there is no alternative yet until Swift 4, so you’ll have to ignore the warning if you want to “build clean” (e.g. with no warnings). If you don’t implement that last one, you won’t be able to use string interpolation like:

"item #\($0)"

Wrapping Up

I’m going to keep playing with it. Once I get pretty comfortable about the syntax, I’ll post it up to my github account.

Oh… and just to show the comparison of what the code looks like without the operator helpers:

You know, just the terrifying normal HTML element construction you see in pretty much every OOP language.

UPDATE @ 10:58PM

While the <| is “clever”, I think I like this API usage better:

h1("class", "welcome", "id", "title") |> "Welcome to Swiccup",

To each their own though and your mileage may vary.

Swiccup, Round 2