inaka

Latest blog entries

/
SpellingCI: No more spelling mistakes in your markdown flies!

Feb 14 2017 : Felipe Ripoll

/
Fast reverse geocoding with offline-geocoder

Do you need a blazing fast reverse geocoder? Enter offline-geocoder!

Jan 18 2017 : Roberto Romero

/
Using Jayme to connect to the new MongooseIM REST services

MongooseIM has RESTful services!! Here I show how you can use them in an iOS application.

Dec 13 2016 : Sergio Abraham

/
20 Questions, or Maybe a Few More

20 Questions, or Maybe a Few More

Nov 16 2016 : Stephanie Goldner

/
The Power of Meeting People

Because conferences and meetups are not just about the technical stuff.

Nov 01 2016 : Pablo Villar

/
Finding the right partner for your app build

Sharing some light on how it is to partner with us.

Oct 27 2016 : Inaka

/
Just Play my Sound

How to easily play a sound in Android

Oct 25 2016 : Giaquinta Emiliano

/
Opening our Guidelines to the World

We're publishing our work guidelines for the world to see.

Oct 13 2016 : Brujo Benavides

/
Using NIFs: the easy way

Using niffy to simplify working with NIFs on Erlang

Oct 05 2016 : Hernan Rivas Acosta

/
Function Naming In Swift 3

How to write clear function signatures, yet expressive, while following Swift 3 API design guidelines.

Sep 16 2016 : Pablo Villar

/
Jenkins automated tests for Rails

How to automatically trigger rails tests with a Jenkins job

Sep 14 2016 : Demian Sciessere

/
Erlang REST Server Stack

A description of our usual stack for building REST servers in Erlang

Sep 06 2016 : Brujo Benavides

/
Replacing JSON when talking to Erlang

Using Erlang's External Term Format

Aug 17 2016 : Hernan Rivas Acosta

/
Gadget + Lewis = Android Lint CI

Integrating our Android linter with Github's pull requests

Aug 04 2016 : Fernando Ramirez and Euen Lopez

/
Passwordless login with phoenix

Introducing how to implement passwordless login with phoenix framework

Jul 27 2016 : Thiago Borges

/
Beam Olympics

Our newest game to test your Beam Skills

Jul 14 2016 : Brujo Benavides

/
Otec

Three Open Source Projects, one App

Jun 28 2016 : Andrés Gerace

/
CredoCI

Running credo checks for elixir code on your github pull requests

Jun 16 2016 : Alejandro Mataloni

/
Thoughts on rebar3

Thoughts on rebar3

Jun 08 2016 : Hernán Rivas Acosta

/
7 Heuristics for Development

What we've learned from Hernán Wilkinson at our Tech Day

May 31 2016 : Brujo Benavides

/
See all Inaka's blog posts >>

/
Function Naming In Swift 3

A photo of Pablo Villar wrote this on September 16, 2016 under functions, inaka, ios, naming, signatures, swift, swift3 .

Yesterday, I started to migrate Jayme to Swift 3. It was my very first experience migrating Swift 2.2 code to Swift 3. While it's been cumbersome, I have to admit it couldn't have turned out another way: Swift 3 is very different from older versions; most of the changes are abrupt, and take time to think of. The good part is that it's for our own sake: The more Swift 3 code I write, the happier I feel. 😃

There have been many, many decisions I had to take regarding changes in code. What's more, it's not just about translating the code, but also dividing the whole migration process into steps, and take it little by little, patiently. Changes in code is just one of those steps.

If you have already decided to start migrating your codebases, I recommend this article as a good kickstart.

Hopefully, in a near future, I'll write a blogpost about my experience, covering the whole process and wrapping up most of those decisions I've been facing. But for now, I will just focus on one of those, which I consider being the most important one so far: How to write function signatures properly.

The Basics

Let's start by understanding that function naming in Swift 3 behaves differently than in Swift 2.

In Swift 2, the label for the first parameter of a function is implicitly omitted when you call the function, in order to follow the good ol' Objective-C conventions that we've been carrying since then:

// Swift 2 
func handleError(error: NSError) { }
let error = NSError()
handleError(error) // Looks like Objective-C

In Swift 3, instead, the first parameter label can be omitted in a function call, but by default, it is not:

// Swift 3
func handleError(error: NSError) { }
let error = NSError()
handleError(error)  // Does not compile!
// ⛔ Missing argument label 'error:' in call

So, the first fix would be:

// Swift 3
func handleError(error: NSError) { }
let error = NSError()
handleError(error: error)    
// Had to write 'error' three times in a row!
// My eyes already hurt 🙈

At this point, you can realize how tiresome and repetitive your code could become...

That said, you'll want to omit the first parameter label in the function call. But remember, in Swift 3, you have to be explicit about it:

// Swift 3
func handleError(_ error: NSError) { }
// 🖐 Notice the underscore!
let error = NSError()
handleError(error)  // Same as in Swift 2

This is the typical change that would occur to your functions when you run the Xcode migrator.

Notice the underscore in the function signature: It points out that the first parameter will not require a label when you call the function. This way, we can keep the function calling like in Swift 2.

Furthermore, you can realize that Swift 3 is more consistent and easier to understand when it comes to functions naming: All parameter labels are treated the same; there is no such thing as treating the first one differently.

This code will compile, but you still need to go a step further in order to stick to the Swift 3 API design guidelines.

☝️ A piece of advice: Read the Swift 3 API design guidelines once and again. Every day in the morning, if necessary, until you get used to the new way of writing Swift code.

One Step Further: Da Pruning

Pruning

Observe how repetitive this line of code is:

handleError(error)

In order to make it less repetitive and more concise, you can prune the redundant type name from the function signature:

// Swift 3
func handle(_ error: NSError) { /* ... */ }
let error = NSError()
handle(error)   // Type name has been pruned
// from function name, since it was redundant

This is shorter, clearer, more concise, and encourages developers to follow the Swift 3 API design guidelines (yes, read them again, and again!)

Notice that the function call is clear. We can know what the function parameter is expected to be because of two facts:

  • We know its type.
  • And also, that type denotes exactly what the parameter is expected to represent (an error, in this case, there is no doubt about it).

It's Not Always A Matter Of Pruning

Now, it's time to be careful! ⚠️

There are lots of scenarios where the latter fact I mentioned above doesn't actually happen. In other words, the parameter's type does not reflect what the parameter itself is supposed to represent.

Consider the following example:

// Swift 2
func requestForPath(path: String) -> URLRequest {  }
let request = requestForPath("local:80/users")

If you try to migrate that code to Swift 3, by following what we've learned so far, you will end up with something like this:

// Swift 3
func request(_ path: String) -> URLRequest {  }
let request = request("local:80/users")

This is confusing and not really readable. Let's enhance it just a bit:

// Swift 3
func request(for path: String) -> URLRequest {  }
let request = request(for: "local:80/users")

Now, while this is more readable, it doesn't solve the problem I mentioned above.

At the moment of calling this function, how can you know that what you need to pass in is a path? All you can know beforehand, because of Swift's static typing, is that the parameter is expected to be of String type, but there's no clue that you need to pass in a path there.

There are plenty of these scenarios where the parameter type isn't meaningful to what it should represent, for instance:

  • A String not always represents a path.
  • An Int not always represents a status code.
  • A [String: String] not always represents an HTTP header.
  • And so on...

⚠️ My advice up to here: Always take your pruning shears with caution!

Back to the code, a first approach to solve this issue could be appending the name of the parameter to the argument label, making it explicit in consequence:

func request(forPath path: String) -> URLRequest {  }
let request = request(forPath: "local:80/users")

This code is clear, compiles and does follow the guidelines. 🎉 Hooray!

Hooray

You can stop reading here, but hang on, the best part is yet to come...

Now, notice this wording in the function declaration:

func request(forPath path: String) -> URLRequest {  }
// The word 'path' appears twice

Even though this ain't evil, and in most scenarios this is still correct and will work out well, there's a way to avoid it.

More about this in the following section….

The Trick You (Probably) Didn't Know

The idea is simple: Make the parameter type reflects its content, in order to be able to prune with no mercy.

Prune with no mercy

What if I told you…?

typealias Path = String      // To the rescue!

func request(for path: Path) -> URLRequest {  }
let request = request(for: "local:80/users")

In this case, your parameter's type and its expected content are coherent and in harmony, because the parameter's type was made explicit through defining Path as a type alias for String.

This way, your function is still intuitive, readable, unambiguous, yet non-repetitive.

Likewise, you can think of some other examples of type aliases that might help in other common scenarios:

typealias Path = String
typealias StatusCode = Int
typealias HTTPHeader = [String: String]
// etc...

These will allow you to write clearer code, as we just saw.

Nonetheless, extremes are not good: Type aliases add an extra layer of complexity to your code, even more if they are nested… So, don't abuse.🖐 While in some cases they can help you out very well, as we've just seen, sometimes they are actually unnecessary and will just make your code harder to follow. Always be disciplined.

It looks nice... BUT

This is an update to the original post. @victorpimentel made a good point on the comments below. Basically, he stated that this last "trick" doesn't actually follow the guidelines: the typealias is just that, an alias. The type of the parameter is still the same (a String in the example), and thus it can lead to problems when overloading that function.

Let's review the example, by adding one more typealias:

typealias Path = String
typealias Host = String

func url(for path: Path) -> URL { }
func url(for host: Host) -> URL { } 
// Error: Same type as the previous one!

let _ = url(for: "local")
// What would the compiler use here?

This, of course, doesn't compile. In this case, we would have to upgrade that typealias to a full type, which would mean more lines of code. A good choice here would be using struct:

struct Path {
    let value: String
    init(_ value: String) { self.value = value }
}

struct Host {
    let value: String
    init(_ value: String) { self.value = value }
}

func url(for path: Path) -> URL { }
func url(for host: Host) -> URL { }
// Works, different types

let url = url(for: Host("local"))
let path = Path("local")
let url = url(for: path)

If you ask me, I would personally avoid these dumb structs that only encapsulate a value, at least for this purpose. In my opinion, and considering these simple examples, defining such structures is not worth the cost of just writing:

let url = url(forPath: "local")

as we did before mentioning the typealias trick.

Conclusion

There are many scenarios you will stumble upon when naming functions in Swift 3.

Code snippets are worth a billion words:

func remove(at position: Index) -> Element {  }
employees.remove(at: x)

func remove(_ member: Element) -> Element?  {  }
allViews.remove(cancelButton)

func url(forPath path: String) -> URL {  }
let url = url(forPath: "local:80/users")

func entity(from dictionary: [String: Any]) -> Entity { /* ... */ }
let entity = entity(from: ["id": "1", "name": "John"])
A photo of

Pablo Villar

iOS Developer