On naming methods with blocks

Mar 17, 2014 by Cesare Rocchi

Recently I have been very busy with the implementation of the BaasBox SDK for iOS and I had to come up with lots of method signatures. It’s 2014 and we all love blocks, so I used them quite extensively. When consolidating the upcoming version I noticed I wasn’t consistent with the naming. Some method was like this:

-(void) loadCurrentUserWithCompletion:(BAAObjectResultBlock)completion;

and some other was like this:

- (void) updateUserWithCompletion:(BAAObjectResultBlock)completionBlock;

Notice the different naming for the last part, the name of the parameter. Sometimes I even used the “Handler” suffix like this:

- (void) logoutWithCompletion:(BAABooleanResultBlock)completionHandler;

I am 100% aware that it doesn’t matter for the correct execution of the app. You can define a method like this

- (void) updateUserWithCompletion:(BAAObjectResultBlock)completionBlock;

and then implement it like this in the .m. It will perfectly work.

- (void) updateUserWithCompletion:(BAAObjectResultBlock)a {
	if (EVERYTHING_IS_OK) {
		a(); // call block
	}
}

Nonetheless, it is pretty likely you are going to use autocompletion to implement the method and a parameter named “a”, although working, doesn’t sound professional, does it? Anyway, my concern here is pretty much on the style, or aestetics if you like, which still matters to me.

So I popped a simple question on Twitter and I got an interesting set of replies.

One good point is brought up by Colin

@_funkyboy second option, ObjC is too verbose as it is! One more serious note, if it was an int value, would you suffix with 'Int'? no!

— Colin Eberhardt (@ColinEberhardt) March 11, 2014

No, if the second parameter were an int I’d not suffix with it. But when I teach I constantly have to explain to newcomers how to correctly read this method:

- (void)loadPath:(NSString *)path completion:(BAAObjectResultBlock)completion;

The source of the confusion is that “completion” is used both in the signature of the method and to name a parameter. In this case I am prone to write the method like this:

- (void)loadPath:(NSString *)path completion:(BAAObjectResultBlock)completionBlock;

so it’s more explicit. After spending a few minutes on this, as replies came in, I thought I should check up what was Apple’s take on the matter. A pretty known method is:

+ (void)animateWithDuration:(NSTimeInterval)duration delay:(NSTimeInterval)delay options:(UIViewAnimationOptions)options animations:(void (^)(void))animations completion:(void (^)(BOOL finished))completion

and, as you can see, there is no “completionBlock”. Then, how did I come up with it? Well, digging a bit more in the documentation it’s easy to find out. NSOperation for example has a property named completionBlock and so has CATransation. AssetsLibrary has a method named

- (void)writeVideoAtPathToSavedPhotosAlbum:(NSURL *)videoPathURL completionBlock:(ALAssetsLibraryWriteVideoCompletionBlock)completionBlock

The new NSURLSession class has

- (NSURLSessionDataTask *)dataTaskWithURL:(NSURL *)url completionHandler:(void (^)(NSData *data, NSURLResponse *response, NSError *error))completionHandler

and I could go on. Unfortunately there is no consistent naming, not even in Apple’s code.

So I went for what I thought made sense for me. Objective-c is verbose per se, people are most likely going to exploit autocompletion, and I like descriptive method names. That’s why I went with completionBlockin my code. I feel it makes everything more readable in general.

And you? How you do name your methods with blocks? Feel free to yell at me on Twitter or App.net.