July 29, 2015

The Braid of Thought

Warning: This one’s not about programming, but it is programming adjacent.

Meditations on Moloch, which I’ve linked to before, is a great article. Alexander finds a few texts and weaves them together, creating an argument that that binds them all. He wraps each text into that braid until an free-standing argument is borne from each of the separate texts.

Chronology is a harsh master. You read three totally unrelated things at the same time and they start seeming like obviously connected blind-man-and-elephant style groping at different aspects of the same fiendishly-hard-to-express point.

A braid of thought — multiple ideas that come together from varied sources that you happened upon almost by chance — follows.

As We May Think is a classic article from 1945, where Vannevar Bush describes a piece of technology he calls the “memex”.

A memex is a device in which an individual stores all his books, records, and communications, and which is mechanized so that it may be consulted with exceeding speed and flexibility. It is an enlarged intimate supplement to his memory.

Upon reading this, many humans rejoice, seeing a reflection of the memex in the modern web or in Wikipedia. Bush seemed to have predicted the widespread dissemination of knowledge that's taken for granted today. But Bret Victor, when reading Bush’s piece, sees failure in the modern web. He writes about this failure in the Web of Alexandria and its follow up.

The web, of course, took a different approach. A million volumes, yes, but our desks remain empty. Instead, when we summon a volume, we are granted a transient and ephemeral peek at its sole instance, out there somewhere in the world, typically secured within a large institution.

This server/client, truth-lives-in-the-cloud, single-point-of-failure model is so engrained in me that when considering a new product, I don’t even evaluate other protocols for data storage and transmission. But there’s so many other templates we can base our information model off of.

Consider email, where every participant keeps a copy of every single dispatch. Consider Git, where each programmer keeps a copy of every single commit. Consider Bittorrent, where each user hosts only the files they care about.

There are also models we haven’t tried. Some datasets are really small, like my contacts. There’s no reason I couldn’t trust all those contacts to 5 or 6 of my close friends. I doubt they’d mind a few hundred extra kilobytes on their drives. Even If I didn’t trust them, I can just heavily encrypt the contacts before I send them over.

It’s made me realize that there’s so many ways we limit ourselves with technology. Modern startups care about very specific things, like streams and attention and keeping your data. Silicon Valley’s conception of what an app can be is very narrow minded, bounded by the dreams of hockey-stick user growth and a high valuation. Paul Ford explains why these types of companies want that type of data in his post about Ashley Madison.

I’ve never built a translucent database-driven system because none of my clients have ever been the least bit interested. They want names, addresses, credit cards, and the like. But they don’t actually need a lot of that data to build a good web service. They need it for potential marketing purposes.

These connections are yet reinforced by Maciej Cegłowski’s Web Design: The First 100 Years. The connections here are left as an exercise for the reader.

If I’m understanding Victor’s argument correctly, it’s the very structure of the web (combined with a thirst for profit, I would probably add) makes these problems arise. We could restructure things and make the web suck less by default. A pit of success of usability and humanity.

To cap off this little mini-web of interconnectivity, last week Mike Caulfield wrote about taking this idea further in Beyond Conversation. He described how links fit into this world: “Links are made by readers as well as writers,” and that was the moment for me that all these threads wound themselves into a much stronger braid.

We have values: links shouldn’t rot; users should have control of their data; media companies should serve users, and not the other way around. These values are incompatible with the Internet in its current conception, and we can’t build the future we want on top of a foundation that won’t support it.

Caulfield’s general solution is for each user to create her own wiki. A personal wiki has never had much appeal for me, since I don’t have a category of stuff I write that I wouldn't publish here. I don’t really write much privately. However, you could take all the pages I love, all the pages I think are important, all the pages I think are mildly interesting, all the pages I’ve seen, all the conversations I’ve had, and all the pictures I’ve taken and save them on my computer. Make it searchable. Now you’re talking about something I really understand.

Allow me to make links and create associations on top of these documents and this very blog post becomes a lot easier to research and write. Chat logs that have links in them should point to the pages that they link to; those pages should link back to the chat logs. What if there were two documents I loved that both linked to a third document on the web? I’d probably want to read that. What if documents, web pages, and images could cluster around a physical location? I’d probably want to know when I’m near that spot.

It’s hard to solve the link rot problem in the general case, without downloading the whole Internet. Fortunately, I don’t care about most of the Internet; I only care about the stuff I’ve read. We have so much cheap storage available now that it’s almost criminal not to save all the web pages you look at. But we don’t keep them so someone can sell ads to you more easily; we keep them so you can easily find the stuff you liked and cared about and thought about.

The idea of the “outboard brain” is a technique for using computers for what computers are good at, and freeing up your brain for what brains are good at. This tool is an outboard brain for idea generation. ("An enlarged intimate supplement to his memory"!) I think I remember all of the various articles and writings that lead to this blog post, but what if I haven’t? Maybe I’ve forgotten a thread that would pull this braid in a totally different direction. (Oh, yeah. I just remembered: watching the BBC’s Connections definitely put me in the mood to start thinking about how all these things are related. – ed.) I’m really bad at remembering stuff, and I’d love to relegate that responsibility to a tool that’s great at it.

Computers are for people. Let's make them so.

July 22, 2015

Cache Me If You Can

Core Data is a powerful framework. It seems a lot like an ORM, but its advocates are quick to remind you that it's "actually" an object persistence framework. I think that's how they stomach not being able to run arbitrary SQL on their own database.

Needling aside, it's the right choice for a lot of apps. When the user has a set of data that's wholly on the device, reach for Core Data. In a lot of the cases I've worked on recently, however, I've found that Core Data functions as more of a cache for objects that canonically live on a server and present themselves through an API.

For cases like these, Core Data is tremendous overkill. Core Data was designed before the prevalance of web services and APIs. It was intended to represent an object graph in its entirety, rather than a small portion that has been downloaded from a service. Since you don't have the whole dataset, you can't even effectively query against it.

The costs to using Core Data are very high, since it's so complex, and the benefits are pretty minimal. Primarily, these types of apps use it to persist the objects so that they'll work in the subway or load quicker on the next launch. Fortunately, we can write a small amount of code to get this effect without having to conform to Core Data's madness.

Foundation provides a protocol called <NSCoding>, which is as simple and elegant as Core Data isn't. By making your models conform to <NSCoding>, you can easily use NSKeyedArchiver and NSKeyedUnarchiver to save your objects to disk. Many built-in objects, like collection types, already conform to <NSCoding>, so you get those for free.

To actually perform the caching, let's make simple object, called SKCache. Caches can be finicky and cause bugs easily, so I'd like to make it very easy to enable and disable.

@implementation SKCache

static BOOL _enabled = YES;

+ (void)enable {
    _enabled = YES;
}

+ (void)disable {
    _enabled = NO;
}

Caches also need a name:

- (instancetype)initWithName:(NSString *)name {
    self = [super init];
    if (!_enabled || !name) self = nil;
    if (!self) return nil;

    _name = name;

    return self;
}

From that name, they'll figure out where in the file system to save themselves.

- (NSString *)hashedName {
    return [self.name MD5String];
}

- (NSString *)cacheFilename {
    return [self.hashedName stringByAppendingPathExtension:@"cache"];
}

- (NSString *)appCacheDirectory {
    NSArray *searchPath = NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES);
    return searchPath.firstObject;
}

- (NSString *)cacheLocation {
    return [[self.appCacheDirectory
     stringByAppendingPathComponent:@"caches"]
     stringByAppendingPathComponent:self.cacheFilename];
}

(Note all the short, simple methods. This object follows the pattern from Graduation.)

Once we have a place to save objects to and fetch objects from, we can easily do that:

- (void)saveObject:(id<NSCoding>)object {
    [NSKeyedArchiver archiveRootObject:object toFile:self.cacheLocation];
}

- (id<NSCoding>)fetchObject {
    return [NSKeyedUnarchiver unarchiveObjectWithFile:self.cacheLocation];
}

@end

This particular type of cache is designed to totally overwrite all of its contents. Blowing it away entirely every time the app gets fresh data ensures there are fewer synchronization bugs. When initializing with a name, you can easily increment the version number when the schema changes or if you accidentally add bad data to it. Since the true data lives on the server, the cache doesn't need to be durable at all. Changing the name of the cache will just leave an extra file in the Caches folder that iOS will clean up when it needs the space.

Once we have a quick and easy way of storing a model object (or array of model objects), we can get to using it. We can set up our cache inside a remote data source.

- (instancetype)init {
    self = [super init];
    if (!self) return nil;

    _fetcher = //set up a fetcher
    _cache = [[SKCache alloc] initWithName:@"com.khanlou.followers?forUser=1234"];
    [self loadFromCache];
    [self fetchData];

    return self;
}

When we first load the data source up, we check the cache for any old content that we can show while we wait for fresh data from the server.

- (void)loadFromCache {
    self.content = [self.cache fetchObject];
    [self informDelegateOfUpdate];
}

Next, we fetch fresh data. When we get it, we can save it in the cache and tell the UI to update via a delegate message.

- (void)fetchData {
    [self.fetcher fetchWithSuccessBlock:^(NSArray *results) {
        self.content = results;
        [self.cache saveObject:self.content];
        [self informDelegateOfUpdate];
    } failureBlock:^(NSError *error) {
        self.content = nil;
        [self informDelegateOfUpdate];
    }];
}

Lastly, we need to accessors to get at the data for our table view:

- (NSInteger)numberOfSections {
    return 1;
}

- (NSInteger)numberOfObjectsInSection:(NSInteger)sectionIndex {
    return self.content.count;
}

- (id)objectAtIndexPath:(NSIndexPath *)indexPath {
    return self.content[indexPath.row];
}

There's not much else to this technique. It seems too simple, almost trivial and useless, but I've found that it solves the problem very well in practice.

Your app might need a more robust cache; for example, you might need one that can be queried or one that needs to be durable. Core Data may still be right for you. If your app is one of the many that are backed by web services, however, your problems aren't the same problems that Core Data was designed to solve, and you should examine simpler solutions.

July 15, 2015

State Negotiations

Functional programmers talk about two things a lot — avoiding side effects and avoiding state. At first, this seems impossible: how the heck am I supposed to write code without side effects and without state? The whole point of programs are to do stuff and remember things! Avoiding side effects is still something I'm figuring out, but this week, I have some tips and tricks on avoiding state.

I've had the most luck with this approach: don't try to totally avoid state, but to limit it wherever possible.

There are lots of techniques for limiting state, and I'll list a few here. It isn't complete, but I hope that it provides enough a jump start to understand the general pattern.

Understating

The broad strategy here in all of these ideas is to reduce the number of instance variables you have, which simplifies your classes. Let's take a simple example, like a table view controller. If you're not using Apple's built-in UITableViewController, you might have an extra @property UITableView *tableView. This generates an additional instance variable. Your -loadView method might look like this:

- (void)loadView {
    UITableView *tableView = [[UITableView alloc] initWithFrame:CGRectZero style:UITableViewStylePlain];
    tableView.dataSource = self;
    tableView.delegate = self;
    self.tableView = tableView;
    self.view = tableView;
}

While it seems easy enough to keep both of these properties in sync, what's actually going on is that one is acting as a "cache" of sorts for the other. Keeping a cache in sync with the primary is always hard, even when it looks easy up front. Even the best programmers make mistakes. Instead, you can use a little-known feature called covariant return types to redeclare the view property with the correct type:

@property (nonatomic) UITableView *view;

Mark it as @dynamic:

@dynamic view;

And then forward the tableView message to the view property:

- (UITableView *)tableView {
    return self.view;
}

With covariant return types, there's no casting required! The compiler knows what you intend. You're using a computed property and nothing needs to be kept in sync anymore because there's nothing to be kept in sync!

Unite the States

Another way to limit instance variables is with state machines. I've written about state machines here before. Before state machines you might have a mish-mash of properties describing the state of, say, a network request:

@property BOOL isUnsent;
@property BOOL isFetching;
@property BOOL isCompleted;
@property NSError *error;
@property NSArray *results;

The problem is that the "space" of this state is huge, and large swaths of that state space are are invalid. For example, what does it mean if more than one of the BOOL properties are YES? What if none of them are YES? What if isFetching is YES and the error had a value? To solve this problem, you can keep one property around:

@property SKRequestState *state;

This state property can have store values of different types, like SKLoadingState, SKErrorState (which stores the error), and SKCompletedState (which stores the results). You can then make those properties readonly and forward them directly to the state property.

- (BOOL)isUnsent {
    return self.state.isUnsent;
}

- (BOOL)isFetching {
    return self.state.isFetching;
}

- (BOOL)isCompleted {
    return self.state.isCompleted;
}

- (BOOL)error {
    return self.state.error;
}

- (BOOL)results {
    return self.state.results;
}

All states respond to each of those messages, returning nil where necessary. This way, while the external surface of the object is still the same, you'll never fail to keep the class in internal synchrony.

If you've got a primitive, like a BOOL or an NSInteger in a class, you can ask yourself: is this really just a number, or do I need to wrap it in something that ascribes meaning to it?

If there are two or more primitives in your class, ask: are they unrelated, or should I formalize their relationship in code?

If a property is nil for part of the object's lifecycle, ask: what meaning is hidden in the nothingness of this property, and how can I make that meaning more obvious to the reader of my code?

Using state machines helps enforce honesty about what's complicated.

The Null Hypothesis

Imagine a presenter that downloads a user object from the server and exposes an interface for displaying that user. Sometimes, the presenter encounters an error and displays a different message for the user's name.

@implementation SKUserPresenter

- (void)fetchUser {
    [self.fetcher fetchWithSuccessBlock:^(SKUser *user) {
        self.user = user;
    } failureBlock:^(NSError *error) {
        self.userFetchError = error;
    }];
}

- (NSString *)name {
    if  (!self.userFetchError) {
        return self.user.name;
    }
    return @"User not found.";
}

//...

@end

This object is now keeping an extra thing (userFetchError) around just so it can handle a special case. The current intention of this code is that either user or userFetchError can have values, but never both. However, you aren't constrained by the design of the class to ensure this invariant is maintained.

Another member of your team, perhaps future-you, could easily cause user and userFetchError to both have values. To solve this problem, we can constrain our instance variables better by using the Null Object pattern.

@implementation SKUserPresenter

- (void)fetchUser {
    [self.fetcher fetchWithSuccessBlock:^(SKUser *user) {
        self.user = user;
    } failureBlock:^(NSError *error) {
        self.user = [SKMissingUser new];
    }];
}

- (NSString *)name {
    return self.user.name;
}

//...

@end

If you wanted to go the extra mile, you could initialize the SKMissingUser with the error, and have it pull its message from the type of error. The broad pattern is the same, however: fewer instance variables, more simplicity.

The Fourth Estate

When limiting state, I find the following rules of thumb to helpful.

  1. Using fewer instance variables is better than using more.
  2. Removing reliance on primitives gives meaning to an object's state as it is exposed internally.
  3. Using computed or readonly properties gives meaning to an object's state as it is exposed externally.
July 8, 2015

Templating Update

I've put my new networking code in a small new codebase, and as I mentioned last week. There were a few extras that I built for it that I wanted to mention. Writing in Swift for a week was nice, but it's back to home territory, where I can be extra effective.

Multipart Requests

One of the first roadblocks I hit when using the new networking library was multipart requests. A multipart request is just a request with a special body that can have text and values mixed in with raw data. It's ideal for uploading images and other big files. This document at the W3C explains the standard in an effective and accessible way.

To support multipart requests, I needed a new request builder, and I needed SKSendableRequest to accept an injected request builder, so I changed its primary initializer to accept a request builder and changed its old initializer to be a convenience method.

@implementation SKSendableRequest

- (instancetype)initWithRequestBuilder:(id<SKRequestBuilder>)requestBuilder {
    self = [super init];
    if (!self) return nil;

    _requestBuilder = requestBuilder;

    return self;
}

- (instancetype)initWithRequestTemplate:(id<SKRequestTemplate>)template {
    SKRequestBuilder *requestBuilder = [[SKRequestBuilder alloc] initWithRequestTemplate:template];
    return [self initWithRequestBuilder:requestBuilder];
}

Multipart requests also send a boundary as part of the Content-Type; this boundary defines where each "part" ends and the next begins. This is sent up in the header of the request itself.

- (NSDictionary *)headers {
    return @{
             @"Accept": @"application/json",
             @"Content-Type": self.contentType,
             };
}

- (NSString *)contentType {
    return [NSString stringWithFormat:@"multipart/form-data; boundary=\"%@\"", self.boundary];
}

- (NSString *)boundary {
    return //a random string here
}

This boundary property was also exposed as an optional part of the <SKRequestTemplate> protocol so that the request builder could access it. (It's also added to the safe template as well.) Request templates that don't need can ignore it. For the multipart request builder, it's initialized with a template and some data.

@implementation SKMultipartRequestBuilder <SKRequestBuilder>

- (instancetype)initWithRequestTemplate:(id<SKRequestTemplate>)template data:(NSData *)data {
    self = [super init];
    if (!self) return nil;

    _safeTemplate = [[SKSafeRequestTemplate alloc] initWithTemplate:template];
    _data = data;

    return self;
}

Most of this request builder is similar to the normal request builder, but building the HTTP body is different. This particular multipart request builder is designed for only one "part", but it could be generalized to accept multiple parts.

- (NSData *)HTTPBody {
    NSMutableData *body = [NSMutableData data];
    [body appendData:[self.bodyBeforePart dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:self.data];
    [body appendData:[self.bodyAfterPart dataUsingEncoding:NSUTF8StringEncoding]];
    return body;
}

- (NSString *)bodyBeforePart {
    NSMutableString *string = [NSMutableString string];
    [string appendFormat:@"--%@\r\n", self.boundary];
    [string appendFormat:@"Content-Disposition: form-data; name=\"attachment\"; filename=\"filename\"\r\n"];
    [string appendFormat:@"Content-Type: %@\r\n\r\n", @"image/jpeg"];
    return string;
}

- (NSString *)bodyAfterPart {
    return [NSString stringWithFormat:@"\r\n--%@--\r\n", self.boundary];
}

- (NSString *)boundary {
    return self.safeTemplate.boundary;
}

Separating out request construction from request sending early in the process of designing this networking code made it obvious exactly where multipart request construction fits into the structure of the library.

Paginatable Requests

Some requests are paginatable, which means they have a page parameter that increments by 1. Let's imagine a endpoint that gets the followers of a user.

@implementation SKFollowersRequest <SKRequestTemplate>

- (instancetype)initWithUserID:(NSString *)userID {
    self = [super init];
    if (!self) return nil;

    _userID = userID;

    return self;
}

- (NSURL *)baseURL {
    return [NSURL URLWithString:@"api.khanlou.com"];
}

- (NSDictionary *)parameters {
    return @{};
}

- (NSString *)path {
    return [NSString stringWithFormat:@"users/%@/followers", self.userID];
}

@end

Right now, this request is awesome. It's initialized with everything it needs, it can't be modified, and it's easy to read and process. If we wanted to paginate this request, we'd have to add an extra parameter called page to the request. We'd need either a mutable property called page that we could update, or we include it in the initializer, preventing the mutation.

What if we had three more endpoints that were all paginated in the same way? Now we've got some duplication, and we'd love handle pagination in some kind of generic way.

Here is the part of the blog post where I pretend to propose using inheritance to solve the problem, and then describe why it's a bad idea. But inheritance doesn't even make sense here. We could subclass all our paginatable requests from one class, but then we'd have to initialize with the right page and merge each request's parameters with its superclasses. It wouldn't actually save us anything.

Ideally, the request template wouldn't even know that it was paginatable. To that end, let's use decoration to add a page parameter to any request we want. Let's start with an initializer that takes a template and a page. Note that SKPaginatableRequest takes a template but also conforms to templateness. This is the pattern from Nestable.

@implementation SKPaginatableRequest <SKRequestTemplate>

- (instancetype)initWithRequestTemplate:(id<SKRequestTemplate>)template page:(NSInteger)page {
    self = [super init];
    if (!self) return nil;

    _template = template;
    _page = page;

    return self;
}

Let's include a convenience initializer for the first page. We're not monsters.

- (instancetype)initWithRequestTemplate:(id<SKRequestTemplate>)template {
    return [self initWithRequestTemplate:template page:1];
}

If you'll remember, the SKRequestTemplate protocol requires a baseURL, so we have to add that to keep the compiler happy.

- (NSURL *)baseURL {
    return self.template.baseURL;
}

For all of the other parameters, like method, path, etc, they're optional, so we don't need to supply implementations for them. Objective-C allows us to forward any messages to a "friend", with -forwardingTargetForSelector:. We know that SKSafeRequestTemplate wraps each property with -respondsToSelector: checks, so we just have to make sure to update the implementation of -respondsToSelector: as well.

- (BOOL)respondsToSelector:(SEL)aSelector {
    return [super respondsToSelector:aSelector] || [self.template respondsToSelector:aSelector];
}

If the runtime can't find a particular implementation in this class, it should just go to the template. If a method can't be found there either, it will just blow up, as expected.

- (id)forwardingTargetForSelector:(SEL)aSelector {
    return self.template;
}

For the parameters property, we want to do something special. We'll get the page number, and add all the parameters from the request itself. Note the order: we won't overwrite anything from the parameters the original request gives us. Instead, we allow the original request to overwrite our parameters.

- (NSDictionary *)parameters {
    NSMutableDictionary *dictionary = [@{@"page": self.pageAsString} mutableCopy];
    if ([self.template respondsToSelector:@selector(parameters)]) {
        [dictionary addEntriesFromDictionary:self.template.parameters];
    }
    return [dictionary copy];
}

- (NSString *)pageAsString {
    return [NSString stringWithFormat:@"%@", @(self.page)];
}

Finally, before we close out this class, we'll add one nice little touch. Because our pagination is now genericized, we can add nice things like this in one place and get the benefits of them everywhere. Without -requestForNextPage, objects using this class would have to ask what the current page is, and then construct the request themselves. This way, we're telling, not asking.

- (BAKPaginatableRequest *)requestForNextPage {
    return [[BAKPaginatableRequest alloc] initWithRequestTemplate:self.template page:self.page+1];
}

@end
June 30, 2015

Protocol-Oriented Networking

Crusty, the antagonistic character from WWDC 2015 Session 408, has been making the rounds on the blogosphere, writing about protocol-oriented programming. For me, protocol extensions in Swift are easily the coolest new feature, because they enable us to add behavior to a set of data easily.

In a post from a few weeks ago called Templating, I describe a flexible networking architecture, that relies heavily on protocols to define and send network requests. It's been working well in practice, and a few cases popped up where the architecture made it really easy to handle new unexpected request types. I hope to write about those soon.

For this post, I'd like to examine the new protocol extensions, and what they can do for this networking design. Ultimately, what we were doing in the Templating post was adding behavior to a set of data. Since I wrote it first in Objective-C, we did it with decoration.

With Swift 2, however, while we could continue to use decoration to wrap our data with new functionality, we've been given a new power with protocol extensions. Protocol extensions let us add concrete methods to a protocol that are dependent on the abstract methods in that protocol. It's a form of the template method pattern, but one that doesn't rely on inheritance.

I'm still very new at the Swift stuff, so you'll have to forgive my sins.

Let's define a lighter version of the SKRequestTemplate protocol from the previous post, but in Swift this time. Since we're adding sendRequest() directly onto the protocol, it's no longer a template, but the request itself.

protocol Request {
    var baseURL : NSURL? { get }
    var method : String { get }
    var path : String { get }
    var parameters : Dictionary<String, String> { get }
}

The baseURL property is marked as an optional, becuase -[NSURL URLWithString:] returns an optional by default. Since there's no good default for a URL (like the empty string is for strings), we'll prevent the user of our networking protocol from having to use a scary bang and allow her to return an optional here.

Okay, let's define our first request. We'll use Github's Zen endpoint, which just returns a short proverb as a string.

struct ZenRequest : Request {
    let baseURL = NSURL(string: "https://api.github.com/")
    let path: String = "zen"
}

Uh-oh, the compiler is already complaining. Swift wants to require us to return something for the method and parameters. That would make this request ugly, though, so we won't be doing that. We could mark each property with the optional keyword, but then we have to mark the whole protocol as @objc, and I want to make this as Swifty as possible. (Ash Furrow lays out this problem neatly in his post, Protocols and Swift.)

Fortunately, we're saved by protocol extensions here. We can give a default implementation for these properties in an extension, and we can leave it out of the individual request structs.

extension Request {
    var method : String { return "GET" }
    var path : String { return "" }
    var parameters : Dictionary<String, String> { return Dictionary() }
}

Now let's add our sendRequest function to the RequestTemplate:

extension Request {
    func buildRequest() -> NSURLRequest? {
        guard let baseURL = baseURL else { return nil }
        guard let URLComponents = NSURLComponents(URL: baseURL, resolvingAgainstBaseURL: true) else { return nil }
        URLComponents.path = (URLComponents.path ?? "") + path
        guard let URL = URLComponents.URL else { return nil }
        let request = NSMutableURLRequest(URL: URL)
        request.HTTPMethod = method
        return request
    }
    func sendRequest(success success: (string: String) -> (), failure: (error: ErrorType) -> ()) {
        let session = NSURLSession.sharedSession()
        guard let request = buildRequest() else { return }
        guard let task = session.dataTaskWithRequest(request, completionHandler: { (taskData, taskResponse, taskError) -> Void in
            if let taskError = taskError {
                failure (error: taskError)
            } else if let taskData = taskData {
                guard let string = NSString(data: taskData, encoding: NSUTF8StringEncoding) as? String else { return }
                success(string: string)
            }
        }) else { return }
        task.resume()
    }
}

Wow, look at all those guard let statements! Exclamation points are for your writing, not your code. We can now create and send our request:

ZenRequest().sendRequest(
    success: { string in
        print(string)
    },
    failure: { error in
        print(error)
})

This is a really simple version of templated requests (I left out a few complexities, like parameters, headers, JSON parsing, etc), but I certainly like how succinct it is. A GET request with no parameters is only a few lines of code. Supporting different types of requests, such as multi-part requests, means overriding the buildRequest method, and returning whatever cooked URL request is appropriate.

June 16, 2015

Declarations

“Declarative” and “imperative” are often used as substitutes for “object-oriented” and “functional”. Conflating “declarative” and “functional” creates confusion and hurts programmers.

Without picking on Nick specifically (since the internet is replete with examples of programmers making the same mistake), this essay on Swift 2’s errors serves as an example. Writers that make this mistake often use the word "imperative" as a thinly-veiled insult against OOP.

The value of declarative code is in describing what you’d like to do, rather than concerning yourself with how to perform the task. Let’s examine one of the standard examples that functional programmers use to explain how imperative and declarative code are different. Imperative code is using a for-loop to iterate over an array and perform some task:

var numbers = [1,2,3,4,5]
var total = 0

for(var i = 0; i < numbers.length; i++) {
  total += numbers[i]
}
console.log(total) //=> 15

On the other hand, the declarative style lets you define how each element in an array should be incorporated, via a block, and the reduce method handles applying that incorporation to each element. We no longer have to concern ourselves with how to merge the values, because reduce handles that for us.

var numbers = [1,2,3,4,5]

var total = numbers.reduce(function(sum, n) {
  return sum + n
});
console.log(total) //=> 15

Without question, this second solution is preferable. And it does have the word function in it. But we should resist calling solutions that use blocks or functions “declarative”, because there’s nuance here. I can write code that’s more imperative than the first solution: a C array where elements in the array are mapped directly onto an unbroken block of memory. Or worse: assembly that reads each element into a register and adds it to itself.

And I can also write code that’s more declarative than the second solution — a message with no parameters that describes exactly what to do, without saying how to do it:

[numbers sum];

Now, I’d probably never write a method like this. But it’s certainly more declarative. Now I don’t even care how the numbers are added together, and as a cherry on top, there’s no blocks or functions seen anywhere — just a message. Maybe it’s implemented with reduce under the hood, or maybe there are some optimizations in place, but they’re invisible and uninteresting to me. If you think sum is a weird method for an array, think about something like reverse, which could be implemented in terms of reduce, but normally isn’t.

Imperativity-declarativity is a spectrum, and that spectrum lies on an orthogonal axis to the functional/object-oriented divide. As we build abstractions, we go up on the declarativity scale. That’s what reduce (and its friends) are: great abstractions. Abstractions are awesome. If you can understand some concept in the general case, that catapults your thinking much further than if you just dealt the concept in its specific form. Great abstractions don’t have to be complicated to be useful. An Objective-C implementation of map can be done in 5 lines of code.

It’s easy to write imperative code in both functional and object-oriented languages. However, when writing code in either style, great declarative code and great abstractions help increase the facility we have in our domain.

June 3, 2015

Why I don’t write Swift

Often, readers will ask me why all my blog technical posts are in Objective-C, and not Swift. I don't write blog posts in Swift because I don't write code in Swift. There are three big reasons for that.

Swift is not production-ready

Trying to use Swift in any professional capacity is a joke. A very cruel joke. The "tooling" is terrible: compilation speed has been abysmal, and SourceKit spent the better part of the year as a punchline.

Last year, at WWDC 2014, Apple claimed that changes to Swift over the course of the year would probably break source compatibility, but that binary compatibility would be maintained (Apple dev forums). That's now rumored to be a goal for WWDC 2015:

With iOS 9 and OS X 10.11, we are told that this will change: Swift is planned to reach what is known as “Application Binary Interface (ABI) stability,” and its code libraries will therefore be pre-installed within the new iOS and Mac operating systems.

Even if they could have maintained binary compatibility all year, the source changes will break old versions of your code from compiling. This means awesome tools like git-bisect are completely useless. Being able to hop to past versions of your app is part of the value of version control and writing code in Swift ruins it.

I understand and accept the "release early, release often" philosophy, and I'm glad the Swift team has embraced it. It's good to polish Swift in public rather than in private. However, for someone who maintains their livelihood through code, writing that code in such a fledgling language is dangerous. It's never been smart to program using the bleeding-edge technologies. How many times do we have to be bitten before we become a little shy?

Swift is complicated

Swift is not a simple language. This Quora answer by Rob Rix is bound to become an instant classic. I don't even understand how some of these bullet points can be real.

  • enum cases act like functions, but are not functions.
  • The rules for overriding a superclass’ init are Byzantine to the point of impossibility.

At 10:05 in Build Phase 82, the hosts discuss methods versus computed, lazy, and stored properties. There are so many little rules to know about!

How do you choose whether to use a struct or a class? Well, I hope you're ready to memorize a bunch of arcane rules for how these two (nearly identical!) things work.

There's so much new stuff to learn about. But it's not the good kind of learning, where you expand your mind and discover new ways of thinking and working. It's rote memorization of the six new inscrutable ways to make readonly properties. Learning that stuff won't make you a better programmer or thinker, it'll make you better at working around Swift.

Objective-C has plenty of complexity in it, given that it's a superset of C. But we had a chance to totally change that, and we dropped the ball. Designing languages isn't easy, especially languages that are going to be used widely in practice. But Swift tries to be great at both functional and object-oriented programming, and ultimately, becomes awkward at both.

I'm not good at Swift

The final big reason I don't write Swift is that I don't think I can write good Swift yet. I'm not really convinced that any of us can. Our job is to deliver timely, high-quality software, and there's tons of experience doing that in Objective-C.

Don't get me wrong: that doesn't mean I don't think I can write great Swift ever, or that it's not worth learning. It's just not worth shipping code in right now. I love reading the blog posts, with people exploring and researching and trying to understand all the new things we can make. One day I hope I'll understand transducers and lenses and functors and closed groups. Ultimately though, for the near- to mid-term future, I can ship much better code with my Objective-C knowledge, and anything I do in Swift will be fundamentally experimental.

It'll be interesting to see what next week's announcements bring us. I'd love to eat my words and see some new stuff in Swift that is worth all the pain. My original plan was that I'd wait a year before writing any Swift, and I hope that I don't have to wait any longer. My suspicion, though, is that we'll see a more stable Xcode 7, and Swift 2.0, which will bring us a little cleaned-up syntax and not much else.

Post-WWDC update: Protocol extensions are so so so cool, but ultimately, I think my stance will stay the same. Via Michael Tsai, iOS 9 still doesn’t have ABI compatibility. My new plan is that once Swift is source compatible with previous versions, the next new app I write after that will be all Swift. I don’t want my code to break when I go back in git, and I don’t want to deal with the context switching of having Objective-C and Swift in one app.

May 28, 2015

Templating

Last week’s post was about a few common networking patterns. I’ve never been satisfied with any of them, so I wanted to describe how I might structure things. I'm assuming a JSON API over HTTP, but these principles are flexible enough to work with any setup.

What are the goals I have for a networking infrastructure?

I want skimmability, simplicity, composability, and lots of flexibility. Let's take the first two at once. What I want is a single file that describes how a request works. A new developer can glance at that file and understand exactly what that request entails and how it's structured.

I laid out this pattern in Prefer Composition to Inheritance: the request template.

@protocol SKRequestTemplate <NSObject>

@property (readonly) NSURL *baseURL;

@optional
@property (readonly) NSString *method;
@property (readonly) NSString *path;
@property (readonly) NSDictionary *parameters;
@property (readonly) NSDictionary *headers;

@end

You can define a really easy-to-skim object that represents a single request. We have the most fundamental element of the networking request represented as an object. We can't break this down into any smaller objects, and that means it's simple enough.

If I were writing this code in Swift, it would almost definitely be a struct, since it's a just a dumb holder of data. You can keep these objects around as long or short as you like, since all they do is store information. (You can take a look at a fully implemented request here.)

Because it's just a protocol, these objects are super flexible. You can bring your own inheritance heirarchy if you like, for example inheriting from one template that has a base URL built-in and maybe some helper methods.

But these objects can't send any data over the network. To do that, we could we could be lazy and pass the template to some kind of global sender:

[[SKRequestSender sharedSender] sendRequestWithTemplate:loginTemplate];

But that wouldn't be in the spirit of this blog. What would be awesome is if we could use decoration to add a -sendRequest method to this template.

@implementation SKSendableRequest

- (instancetype)initWithRequestTemplate:(id<SKRequestTemplate>)template {
    self = [super init];
    if (!self) return nil;

    _template = template;

    return self;
}

- (void)sendRequestWithSuccessBlock:(void (^)(id result))successBlock failureBlock:(void (^)(NSError *error))failureBlock {
    NSURLRequest *request = //generate a request from a template
    [[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        //handle response
    }] resume];
}

@end

As I wrote this object, I saw that there are two complicated steps that I wanted to break out into their own objects. One is building the NSURLRequest object, and the other is parsing the response.

Request

To generate the request, I made SKRequestBuilder. This class takes a request template and vends an NSURLRequest. Creating the request was originally a method on the SKSendableRequest class, until it started getting gnarly, at which point I graduated it to its own class.

@implementation SKRequestBuilder

- (instancetype)initWithRequestTemplate:(id<SKRequestTemplate>)template {
    self = [super init];
    if (!self) return nil;

    _template = template

    return self;
}

- (NSData *)HTTPBody {
    return [NSJSONSerialization dataWithJSONObject:self.template.parameters options:0 error:nil];
}

- (NSURL *)URL {
    NSURLComponents *URLComponents = [NSURLComponents componentsWithURL:self.template.baseURL resolvingAgainstBaseURL:YES];
    NSString *path = [URLComponents.path stringByAppendingString:self.template.path];
    URLComponents.path = path;
    return URLComponents.URL;
}

- (NSURLRequest *)URLRequest {
    NSMutableURLRequest *mutableURLRequest = [[NSMutableURLRequest alloc] init];
    mutableURLRequest.HTTPMethod = self.template.method;
    mutableURLRequest.HTTPBody = [self HTTPBody];
    mutableURLRequest.URL = [self URL];
    [self.template.headers enumerateKeysAndObjectsUsingBlock:^(NSString *fieldName, NSString *value, BOOL *stop) {
        [mutableURLRequest addValue:value forHTTPHeaderField:fieldName];
    }];
    return [mutableURLRequest copy];
}

@end

For simplicity, I've left out a few details here (like nil checks and query parameter handling). I'll link to a gist at the end of the post which has handles more stuff.

This also changes the SKSendableRequest initializer to create the request builder from the template:

- (instancetype)initWithRequestTemplate:(id<SKRequestTemplate>)template {
    self = [super init];
    if (!self) return nil;

    _requestBuilder = [[SKRequestBuilder alloc] initWithRequestTemplate:template];

    return self;
}

Response

For parsing the response, we need an object that takes an NSURLResponse, NSData, NSError and parses it into a result and an error, which are what are returned to the completion blocks.

@implementation SKResponseHandler

- (instancetype)initWithResponse:(NSURLResponse *)response data:(NSData *)data error:(NSError *)error {
    self = [super init];
    if (!self) return nil;

    _response = response;
    _data = data;

    _error = error;
    _result = [NSJSONSerialization JSONObjectWithData:self.data options:0 error:nil];

    return self;
}

@end

There's one more thing we need to handle. Requests aren't necessarily going to want to return the error from NSURLSession or the JSON result. They might want to use the JSON to generate a local domain object, or they might want to extract errors from the JSON response.

To that end, I made the error and result properties of SKResponseHandler mutable. I also added one more method to the request template, called -finalizeWithResponse:. The template can implement that method to transform the result or error of the response before its returned to the completion block. For example, a login request might implement that method like so:

- (void)finalizeWithResponse:(id<SKResponse>)response {
    response.result = [[SKSession alloc] initWithDictionary:response.result];
}

This way, all the logic tied to a particular endpoint is located in one class, and any class using it gets fully baked objects in their completion block.

Our final -sendRequest method looks like this (again, slightly simplified):

- (void)sendRequestWithSuccessBlock:(void (^)(id result))successBlock failureBlock:(void (^)(NSError *error))failureBlock {
    [[[NSURLSession sharedSession] dataTaskWithRequest:self.requestBuilder.URLRequest completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        SKResponseHandler *responseHandler = [[SKResponseHandler alloc] initWithResponse:response data:data error:error];
        [self finalizeWithResponse:responseHandler];
        if (responseHandler.error) {
            if (failureBlock) {
                failureBlock(responseHandler.error);
            }
        } else {
            if (successBlock) {
                successBlock(responseHandler.result);
            }
        }
    }] resume];
}

One of the big benefits to separating request building and response handling into their own objects is that users can inject whatever request builder they want. If their data comes back in MessagePack format, they can bring their own response handler. The NSURLSession could also easily be injected.

You could easily create an initializer that accepts a request builder -initWithRequestBuilder:, but injecting a response handler is a bit harder, since it's initialized with the response data. To get around this, you could inject a class to be intialized. This is a tough problem and I don't have a great solution for it yet.

I've packaged up this code into a gist. I'm not sure if this code will become a library, but there's a pretty good chance it'll end up as the networking layer for Instant Cocoa.

May 20, 2015

Networking, more like not working

The question that vexes me the most in a new iOS project is the question of how to structure networking code.

Networking code is tough for three reasons. The first two reasons are related. First, it's singular. There's only one internet, you usually have one base URL for your API, and you want to deduplicate as many of the shared headers and URLs and access tokens as possible. Second, since you'll need to access the network from all over, your networking code will need to be globally available. It's just begging to be turned into a singleton.

The final problem is that making a request is a one-time process. It isn't easily represented well in a long-lived object. While a network request maps well to a method on an object, it doesn't easily graduate to a fully-fledged object.

Instant Cocoa itself faces this problem. It's currently built on AFNetworking, but as the Instant Cocoa progresses, using a dedicated library for networking seems more and more extraneous. Especially in a library that I hope other developers will use, I want to keep dependencies to a minimum.

There are a few different approaches that are commonly used, and I'll enumerate them from least elegant to most.

Raw Access

If you're accessing your AFHTTPRequestOperationManager directly, or using NSURLRequest and NSURLSession objects without any abstraction around them, this is what I'd call raw access.

[manager POST:@"https://api.khanlou.com/users/login" parameters:@{ @"username": username, @"password": password } success:^{ ... } failure:^{ ... }];

There's an advantage to the ease and directness of this method, but it comes with some cost. There's no way to name or categorize the API calls. The API is totallly untyped. You can't hide away an logic that needs to be associated with the request, such as saving an auth token or sending notifications to update the UI. You'll also be duplicating code for base URLs, common headers, and the like. Also, tying your code directly to AFNetworking will make it hard to change if you ever decide to move away from such a framework.

For early-stage projects this approach will work fine, but those projects usually level up to late-stage projects, and by that point, you're going to need some organization around your network requests.

Singletons

The next, slightly more abstract, slightly more indirect way to perform your network requests is with a singleton. The interface for such a pattern might look like:

[SKAPI loginWithUsername:username password:password success:^{ ... } failure:^{ ... }];

This is a little bit better than raw access. You can name your endpoints, you can assign types to their parameters, and you can couple logic with the request. It's a decent solution, but it's fundamentally not object-oriented. You'll notice that this is how the Swift version of AFNetworking, Alamofire, works:

Alamofire.request(.GET, "http://httpbin.org/get")

Here, Alamofire is more of a namespace around the request, same as SKAPI above. What you're essentially doing is accessing a global function via that namespace. It works, since API requests fundamentally are just functions (they're fired once, take parameters, return a result), but it still feels weird to try to shoehorn this into a class. There's no state and no sense of self. This is made obvious by the fact that it doesn't matter that I made these class methods rather than instance methods.

Resource-centric

REST tries to map each remote path to an object representation. For example, users/1234 represents a user, and users/1234/follow represents an action being done to that user. If you've got a local representation of that user in the form of a User model, it makes sense to send a message to that model and have it perform the action, like:

[user followWithCompletionBlock:^{ ... }];

This is nice because is slightly more object-oriented, in that you're sending a message to an entity. It maps to REST really nicely. It helps organize the requests in a nice way. You can also intuit things about the endpoint and parameters from innards of the model.

This is how Instant Cocoa's resource gateways work. It works sort of like Active Record (the pattern), but designed to work asynchronously.

There are flaws, though. It's only an interface; one of these other patterns has to actually perform the request. Also, the model probably shouldn't know about how it's connected to its remote representation, given that it probably already handles serialization, conversion for display, and validation logic. Finally, it can't represent singleton resources very well (like /search). Should singleton resources be singleton objects? It's not clear.

Enumerating requests

Ash Furrow's Moya library is another, Swiftier way of handling requests. I don't have a lot of experience with Swift, but I still wanted to take a look at it for this roundup.

enum GitHub {
    case Zen
    // ...
}

extension GitHub : MoyaPath {
    var path: String {
        switch self {
        case .Zen:
            return "/zen"
        }
        // ...
    }
}

extension GitHub : MoyaTarget {
    var baseURL: NSURL { return NSURL(string: "https://api.github.com") }
    // ...
}

You use it by creating a Swift enum with all of your requests, and then extending that enum with protocols that tell Moya what path to use, what base URL to use, and so on. Then you can pass your enum value into a MoyaProvider to perform a request, and it can get any values it needs from methods on the enumeration itself.

This approach is a laudable for a few reasons. It feels pretty idiomatic to Swift, each endpoint has its own type (which is good!), and each endpoint can have its own well-typed parameters, since enums in Swift can take parameters.

The flaws of Moya are mostly in the organization. Moya requires that all of your API paths be in the same big switch. Adding a new API endpoint requires creating a new option in the enumeration, and adding options to all of the switches that need data for that endpoint. While sometimes it can be useful to see all of your endpoints's paths in one place, I'd rather see all of the data related to one endpoint clumped together instead. In other words, I want something more like a struct for each endpoint rather than an enum for all of them.

One object per request

The last solution we're going to cover is making one object for every request. It can be initialized with whatever parameters it needs, knows how to fire itself, and has an internal state machine so that objects can know if the request is midflight or completed or any other state. AFNetworking's NSOperation objects function like this, though you usually don't have to interact with them directly.

[[SKLoginRequest alloc] initWithDelegate:self username:username password:password];

The primary problem with objects like this is that they have a very specific lifecycle. You can't discard them early, because the object will be deallocated and the request won't complete, and you can't keep them around after they're finished, since they're no good anymore (they're in the Completed state and can't — and shouldn't! — be reset). You have to trash them at just the right time, and that's annoying.

There's also a lot of boilerplate around them; you usually only need to vary the path and the parameters. You might be tempted to use inheritance with the Template Method pattern to add shared behavior to these request objects, but that temptation is worth resisting.

The sweet spot

Each of these approaches has its own flaws. Next week, I'll bring together some ideas from previous posts (Prefer Composition to Inheritance, Nestable, and Graduation) to propose something that's flexible, well-architected, and satisfactory from an object-oriented perspective.

May 12, 2015

Throw it all away

Louis CK came onto the scene a few years ago, and he’s been tearing it up ever since. There’s one particular bit of his that has a message that I’ve been feeling the last few months. He remembers being a shitty comedian for 15 years, and in a moment of crisis, he listens to a CD of George Carlin’s comedy:

On the CD they ask him, how do you write all this material? And he says, each year I decide I’d be working on that year’s special, then I’d do that special, then I would throw away that material and start again with nothing. And I thought, that’s crazy, how do you throw away? It took me fifteen years to build this shitty hour, and if I throw it away, I got nothing.

Your ideas feel precious to you when you have them. My ideas certainly have. And that can lead to a fear of publishing them, of acting on them. For me, I fear that if I let go of one idea or another, I’ll never have a new one again.

The ideas in Instant Cocoa have felt precious. Even though those ideas were intended to be open-sourced, it took a year and a half to do so. Most of Instant Cocoa was done by last spring. I’m not sure why it took so long to release. But if I had to guess, I’d say my fear of it ending overrided my desire to see it in the world.

The post ideas for this very blog have felt precious. I’ve got a list of potential blog post topics, and I worry: what am I gonna do when I run out? And I can’t even lean on performing the same material over and over again, like Louis CK. Once I publish something here, it’s out, and it wouldn’t make sense to publish it again.

I’ve been posting on this blog weekly all year, with the exception of March, when I was working on my Úll talk and releasing Instant Cocoa. I’ve published 15 posts since January. It feels like a breakneck speed. If you asked me last year how long I could sustain such a pace, I think I would have answered, “maybe 4 weeks?”.

But I’m still going. And, somehow, even though back in December the list of potential topics had as many items on it as I’ve posted already, it’s still more or less the same length. I can’t explain it.

The act of publishing solidifies the idea into being. Like the Zeigarnik effect, it frees up space in your brain to find the next thing. The next thing will be built on the previous thing, and it’ll be stronger for it. There’s a quote that I can never find about how “the act of writing shows us how bad our thinking is”. Once we start putting pen to paper, the flaws in our reasoning bubble to the top, and we’re forced to deal with them. Tending to those inconsistencies clarifies the missing parts of the idea and shows what ideas should come next.

And as for Instant Cocoa, far from feeling like I’ll never be able to come up with anything else new for it, it now feels like I’m on the verge of a greater thing. I don’t want to call it an MVP, because another metaphor is more appropriate. It feels like an EP, and now I want to spend the time to turn it into an LP.

More ideas will come. Tons of ink has been spilled about how only execution matters, and your ideas are worthless. But rather than using that fact to tear them down, I want to build them up. Your ideas might not be important, but your ability to generate them is. One idea will never change the world; a series of successive ideas built on each other will. You’ll get farther than anyone else, since by fulfilling your ideas you’ll gain access to new parts of knowledge that no one else can. Get your stuff out there.