Skip to content →

Tag: naming

Naming Interface Builder Outlets and Actions

Ever wondered how to name an @IBOutlet property or @IBAction method and felt conflicted over “the right way to do it”? You’re not alone:

In case that’s you, here’s the Apple-sanctioned convention:

  • For @IBOutlets, the property name comes in two parts. First, begin with a description of the contents of the control, such as username, passcode, or authenticationNotification. Then add the name of the control, such as Label, TextField, and Button. The result: usernameLabel, usernameTextField, and passcodeButtons. Examples of what not to do: trustAgentUsername: UITextField and authenticationNotification: UILabel.
  • For @IBActions, the method name simply describes the action; there is no control name suffix as with an @IBOutlet. For example, a UIButton action that capitalizes a word in an associated UITextField would be properly declared func capitalizeWord(sender: UIButton). An action that removes a user would be func removeUser(sender: UIButton). Examples of what not to do: didTapButtontappedDone, or overlayTap.

Specific Apple resources prescribing and modeling this convention include their “Start Developing iOS Apps (Swift)” guide, specifically Lesson 3, “Connecting the UI to Code“, and their discussion on Target-Action in the “Concepts in Objective-C Programming” documentation. Their Swift API Design Guidelines say nothing on the matter, presumably deferring to their elsewhere-stated conventions.

A corroborating resource I found is Matt Thompson’s “IB Outlet / IB Action / IB Collection” article. RayWenderlich.com, while also corroborating, has little to say on this specific issue, giving but one example (out of this particular context, even) of an @IBAction between their Objective-C and Swift style guides.

If you have found yourself asking, “How do I name my IB connections?”, hopefully this clears things up for you. It’s not complicated; it’s just a matter of knowing.

Leave a Comment

Naming Swift Methods

How to name methods in Swift is a fairly common discussion point with my team, and one of repeated frustration for those members new to iOS development. Largely at issue is named parameters: that we use them at all (what is their value?), and how to use them.

To illustrate their value, I present a brief example. Consider this method I wrote that needs to communicate to a delegate when a document object has finished processing an XML representation of a weather layer with a certain name. I named this method as so:

func capabilitiesDocument(document: CapabilitiesDocument, 
  didProcessXMLLayer xmlLayer: XMLElement, 
  withName name: String)

The signature for this method reads:

capabilitiesDocument(_:didProcessXMLLayer:withName:)

I would argue this name communicates very clearly the intent of that method (it’s not unlike the UITableViewDelegate method tableView(_:didSelectRowAtIndexPath:)). In contrast, consider the omission of the external argument names: capabilitiesDocument(_:xmlLayer:name:). Here the method’s purpose is completely lost; named parameters clearly communicate that intent.

Naming methods in this manner may be somewhat of an art; it is not always clear cut. Thankfully, we are not without authoritative guidance.

First, understand Swift has its heritage in the Objective-C community, and Apple has made it clear that Swift adopts the Objective-C style. To this point, the Swift Programming Language Guide states in its discussion on Methods:

Methods in Swift are very similar to their counterparts in Objective-C. As in Objective-C, the name of a method in Swift typically refers to the method’s first parameter using a preposition such as withfor, or by, as seen in the incrementBy(_:) method from the preceding Counter class example. The use of a preposition enables the method to be read as a sentence when it is called.

You don’t need to define an external parameter name for the first argument value, because its purpose is clear from the function name incrementBy(_:numberOfTimes:). The second argument, however, is qualified by an external parameter name to make its purpose clear when the method is called.

The behavior described above means that method definitions in Swift are written with the same grammatical style as Objective-C, and are called in a natural, expressive way.

So there you have it. The goal is a Swift method definition that can be called in a natural, expressive way, as is done with Objective-C.

Given that Apple establishes this link between Swift and Objective-C method naming guidelines, it is reasonable to turn to their Coding Guidelines for Cocoa as an authoritative source for naming not only methods, but also variables, types, delegates, etc. While the guidelines are not 100% applicable to Swift (such as the naming of accessors, which Swift makes implicit), for the most part they are.

Apple does provide some discussion of this in a Swift-specific context in their API Design Guidelines. You will not find any contradictions between this and the Cocoa guidelines, but perhaps some clarifications.

Finally, in the spirit of leading by example, an extremely good source for a practical application of these guidelines are Apple’s framework references, such as the UIKit Framework Reference. These give hundreds upon hundreds of examples of method and property names that follow these conventions.

Happy Swifting!

Leave a Comment