The unbearable frustration of figuring out APIs

The problem is there are a wide class of problems that you want solved but putting on the work will prevent you from actually doing the task because the cost isn't worth the reward. Because it's for a low impact tool. Or you can't imagine yourself dealing with this API again within a year or two by which time it will probably be completely different with v2 of the API.

So, you reach for AI and it works really well. So you start reaching for that more and more...

I remember reading and hearing similar rants from programmers 15 years ago, long before LLMs. The author kept going and figured it out, and probably got some pride and enjoyment from finishing the project in spite of the frustrating moments. That’s what learning to code has always been like.

Gotta say as a Swift dev I agree—followed the link the to Translate docs and was pleasantly surprised to see a discussion section clearly explaining the usage, which is not always the case for Apple APIs! But this wasn’t really just an article about the API. It was about the complexity of trying to build on the stack of Swift/SPM/ParseableCommand/Foundation/Concurrency/Translation without having a good grasp of any of them. I was frustrated reading it, but I think it does point to the underlying knowledge that’s needed to be proficient at something like this. None of it is a particular indictment of Swift as an ecosystem (though there are lots of valid criticisms)-it’s just the nature of development and something that’s massively eroded by relying too much on these ghosts

Swift ultimately is a language that is expected to be compiled by xcode. Package.swift isn’t even properly supported by Xcode still.

Language is meant for using, not learning. Why is Arabic/French/Chinese/etc so difficult?

To be fair, Apple is known for having bad docs (for at least the past 5-10 years) that often don’t have examples or sample code, I think that’s more of an outlier.

I don’t regularly develop in swift, but when I have, I’ve been confused by the docs because they are so clearly auto generated (not LLM, just from the code) and sparse. Listing out constants is next to useless when they are confusingly named and have no description of what they mean or how the affect things.

Agreed. Amusingly, a lot of what makes them worse than some older alternatives is that they "fix" things constantly by reworking how to use them. Older paths may be bad, but effort has been made into getting them to work.

As a Swift dev, I have to say this was a frustrating read.

Apple’s documentation is often very poor, and I will note that Swift Packages (especially CLIs) doesn’t always feel great. As another commenter noted, anything other than Xcode feels like fighting an uphill battle.

But many of your frustrations could be solved by checking not API docs, but just the Swift language guide. You seem perturbed, for example, that the Package initializer expects ordered arguments. It is a basic part of Swift’s design that arguments are always ordered and exclusively are either named or unnamed (never optionally both).

The ghost’s use of semaphores with async/await is a massive red flag in terms of mixing two asynchronous frameworks (Concurrency and GCD). I’d not be surprised if it worked, but that’s really against the grain in terms of how either framework were designed. This is the shortfall of relying on bottled ghosts to learn new tools. I know from experience that the documentation on Concurrency (async/await) is pretty good, and lays out a clear rationale for how it’s intended to be used, but that is a huge piece of documentation and it’s a big hill to climb when all you’re building is a small tool. This is the risk we run when asking AI for help when it itself is ignorant of the actual intended use of the apis and is only trained on the output of developers. Here it’s easy to see that it was faced with a problem of synchronous access to an async function and reached for a common solution (semaphore), despite the fact that semaphores are part of a 10 year old framework, and the async/await keywords are only 2-3 years old!

Anyway, the article reminded me of the challenges of learning a new (programming) language. There’s more to it than just following tutorials and blindly directing AI. I know the feeling, having to currently learn c# at the moment. I can write simple functions and follow the syntax, but I can’t intuitively understand what’s happening like I can with Swift. Is that because Swift is better than C#? Not really- it’s just that I’m fluent in one but not the other. Ironically I guess you probably get this already from learning Mandarin, but you’ve not written an article about how frustrating it is that it inexplicably insists on using tones to express meaning, when English is fine without it(!).

I’m sorry you had a bad experience with Swift. I do genuinely think it’s a great language to write, and the open source Swift Evolution team are great. They are continually pushing for more openness and more cross platform compatibility, and I do like the way that the core of the language is strongly opinionated in a way that makes it clear what’s happening if you do understand the syntax. What’s hard is then the application of Apple’s APIs which are wildly inconsistent and often incomplete. Some are maintained while others are still wrappers for 15 year old objective C that have no concept of modern Swift paradigms. That said, I’d still encourage you to persevere with Swift. Once you get past those rough edges of stdio and UI and get into the heart of a Package, I would expect most of these complaints to disappear!

If so, then you have Two Problems

That's the thing: if you ask the Ghost to write as if a frustrated human, it'll happily do so.

LLMs are good at style transfer in fully general sense, they can introduce typos and bad grammar just as easily as it can correct them.

right but not all things are done for "market value" reasons, and that's kind of my point. If you don't find this stuff interesting, what's the point of building your career in the space?