Clean Code on Andrew Bancroft

Enums Instead of Booleans – An Example Implementation

Wed, 01 Apr 2015 12:00:52 +0000

This blog entry was inspired by Objc.io’s snippet titled “Enums instead of Booleans”. I really loved the clarity that using enumerations brought to even the simplest of examples that was presented in that snippet. If you haven’t seen it, check it out before continuing on!

Objc.io’s snippet focused primarily on the definition and consumption of the enumeration values. What I’d like to focus on here is the implementation of the thing that produces those values for the switch-case that will consume them later on.

Example scenario

To put an example before us, consider the following scenario:

Suppose that we’re building an app that utilizes a subscription-style service to deliver premium content.
Special things, such as providing access to the premium content, need to happen in the app if the user is a Subscriber in good standing.
Other things need to happen, such as denial of access to the premium content, if the user had a subscription, but it’s expired.
Finally, if the user has never had a subscription, we’d still like to deny access to the content, but perhaps offer them the opportunity to subscribe.

Using Objc.io’s idea as a springboard, we could program this in a couple of ways:

1 – We could define a few boolean properties throughout that would indicate the user’s subscription status:

isSubscriber
isSubscriptionExpired
isNonSubscriber

What I find interesting about this approach is that it’s not clear, from looking at the properties, that they’re all mutually exclusive. Can I be a subscriber whose subscription has expired? If my subscription expired, am I a non-subscriber?

It could be that I’ve chosen poor names for the properties, but if I wanted to make clear that the statuses are mutually exclusive, there’s a better way to encapsulate them. Objc.io helpfully pointed us in the direction of that better encapsulation method. Yep… you got it: enumerations!

2 – As the title of the blog entry signals, we could replace the booleans with an enumeration:

1public enum SubscriberStatus {
2    case CurrentSubscriber
3    case ExpiredSubscriber
4    case NonSubscriber
5}

Immediately, this clarifies the mutually exclusive part. Enumerations, by definition, expose mutually exclusive values. By defining the SubscriberStatus enumeration, I’ve made clear that my intent is to have someone be either a CurrentSubscriber, an ExpiredSubscriber, or a NonSubscriber, but not combinations of each.

Not only that, but rather than including complicated branching logic when I need to determine someone’s subscription status, I can simply switch-case over the enumeration possibilities and perform the appropriate behavior.

 1func checkSubscriberStatusForRegistrant(registrant: Registrant) {
 2    // We're coming to the definition of Registrant...
 3    // In fact, Registrant's implementation is the goal of this blog entry!
 4
 5    switch (registrant.subscriberStatus) {
 6    case .CurrentSubscriber:
 7        showPremiumContent()
 8    case .ExpiredSubscriber:
 9        alertExpiredSubscription()
10    case .NonSubscriber:
11        offerSubscription()
12    }
13    
14}

Producing the enumeration values

The one thing that left me scratching my head on at first was the part of the whole scheme that would produce the enumeration values. In my example above, I’ve left out what the implementation of Registrant looks like.

When I’m consuming the enumeration values, I’m riding on the fact that registrant.subscriberStatus has some way of producing a correct SubscriberStatus for the registrant. But what does that look like? Well… here’s one possibility:

 1public struct Registrant {
 2    public var subscriberStatus: SubscriberStatus {
 3        get {
 4            if (noSubscriptionOnFile()) {
 5                return .NonSubscriber
 6            }
 7            
 8            if (subscriptionOverdueForPayment()) {
 9                return .ExpiredSubscriber
10            }
11            
12            return .CurrentSubscriber
13        }
14    }
15    
16    private func noSubscriptionOnFile() -> Bool {
17        // Do what needs to be done to check if the registrant has a subscription on file or not
18    }
19    
20    private func subscriptionOverdueForPayment() -> Bool {
21        // Do what needs to be done to check if the registrant's subscription is overdue for payment
22    }
23}

So as you can see, the thing that produces the enumeration values does have some ifs and Bools in it. I couldn’t really think of another way to do this. To simplify the readability of the subscriberStatus property’s implementation, I’ve abstracted the more complicated computational logic for figuring out whether or not a subscription is on file or if the registrant is overdue for payment into functions.

Even though we do still have some Bools to deal with, what we’ve gained (in my opinion) is clarity on the consumption end. To me, it’s worth it to have the Bool logic buried in one spot so that throughout the rest of my app, I can deal with clear, understandable, enumeration values.

Replace Magic Strings with Enumerations in Swift

Wed, 03 Sep 2014 01:55:54 +0000

“What can I do to avoid these ‘magic strings’ in my code?” – This was the question I asked myself recently as I found myself in prepareForSegue comparing segue.segueIdentifier to in-line hard-coded Strings. This kind of in-line hard-coding of a String for comparison purposes is what I mean by “magic strings” in this article. I knew this felt like a bad idea, but the solution to a cleaner option wasn’t readily apparent to me.

I used to do things like create static string constants, or #define expressions so that I could easily change these values if I ever needed to update them for some reason. You know… back in a former Objective-C developer life when these tactics were available to me. But these options don’t exist in Swift. What to do??

Enumerations to the rescue!

Specifically, Enumerations with pre-populated default values (called raw values).

By creating an Enumeration that stores raw String values, I was able to encapsulate what would otherwise be “magic strings” in a type-safe construct for easier, cleaner use in my code.

The Gist

Consider this fabricated example:

I have a storyboard with one main View Controller that connects to three other View Controllers through three segues: “otherScreenSegue1”, “otherScreenSegue2”, and “otherScreenSegue3” as defined in the utilities panel in Xcode.

An Enumeration encapsulating those segue identifiers might look something like this:

1enum SegueIdentifier: String {
2    case OtherScreenSegue1 = "otherScreenSegue1"
3    case OtherScreenSegue2 = "otherScreenSegue2"
4    case OtherScreenSegue3 = "otherScreenSegue3"
5}

With this Enumeration defined (perhaps in its own .swift file – wherever you deem would be strategic and findable again), the prepareForSegue override can become “magic string”-free:

 1override func prepareForSegue(segue: UIStoryboardSegue!, sender: AnyObject!) {
 2    switch segue.identifier {
 3    case SegueIdentifier.OtherScreenSegue1.toRaw():
 4        println("Going to other screen 1")
 5    case SegueIdentifier.OtherScreenSegue2.toRaw():
 6        println("Going to other screen 2")
 7    case SegueIdentifier.OtherScreenSegue3.toRaw():
 8        println("Going to other screen 3")
 9    default:
10        println("Going somewhere else")
11    }
12}

Alternatively, if you prefer to compare the enum values themselves, you could do the following (thank you to Brandon Knope for pointing this out – I think it looks even cleaner than my original code above!):

 1override func prepareForSegue(segue: UIStoryboardSegue!, sender: AnyObject!) {
 2    if let identifier = SegueIdentifier.fromRaw(segue.identifier) {
 3        switch identifier {
 4        case .OtherScreenSegue1:
 5            println("Going to other screen 1")
 6        case .OtherScreenSegue2:
 7            println("Going to other screen 2")
 8        case .OtherScreenSegue3:
 9            println("Going to other screen 3")
10        default:
11            println("Going somewhere else")
12        }
13    }
14}

This strategy of encapsulating my various segue identifiers in an Enumeration provides me a one-stop-shop for reviewing, and if need-be, updating the String values to match what I’ve set up in my storyboard.

The Details

I’ve chosen an Enumeration with Raw Values, because the other two kinds (Enumerations as Inherent Types, or Enumerations with Associated Values) don’t allow me to do String comparison, or don’t allow me to define a value at declaration-time, respectively.

Notice one critical aspect of the Enumeration: because default raw values are defined, all of the raw values must be of the same Type, as explicitly specified in the declaration line: enum SegueIdentifier: String // All of the enum cases must be Strings

The next important thing to understand is that in order to do actual comparisons with the raw value itself (see the switch statement in my code example above), I needed to call toRaw() on the Enumeration value being used (first code example), or call fromRaw() to convert the segue.identifier string to an Enumeration value (second code example):

1SegueIdentifier.OtherScreenSegue1 // Enum value of type SegueIdentifier
2SegueIdentifier.OtherScreenSegue1.toRaw() // String value, "otherScreen1Segue"
3SegueIdentifier.fromRaw("otherScreenSegue1")! // Unwrapped Enum value of type SegueIdentifier

Conclusion

In addition to segue identifiers, I’m considering using raw value Enumerations to wrap NSNotificationCenter keys as well. Share if you find other nice uses of raw value Enumerations!

So far, this solution has provided me a nice, straight-forward, type-safe way to encapsulate groups of Strings where the urge to fall back to “magic strings” would otherwise be high.

Pick a Delegate… Any Delegate… On Clean View Controllers in Swift

Wed, 27 Aug 2014 04:43:29 +0000

The delegation pattern is ubiquitous in iOS development – the pattern is a “core competency” for developing in Cocoa, and if you program with the iOS SDK for any length of time and you’ll end up writing some code that resembles someInstance.delegate = someDelegate.

One of the toughest things that I’ve experienced is choosing what someDelegate is. All too often, a View Controller ends up being assigned the responsibility of being the delegate for everything in its hierarchy. My question is: Is there a cleaner way?

Let’s pick up on the example I proposed in my recent post about sending e-mails in-app. For “quick and dirty” pragmatism, I just crammed everything into the View Controller with the promise of coming back and (hopefully) showing a cleaner way. Here is a quick link to example posed before if you’d like to review it before proceeding.

What if…

What if we could make some adjustments so that the View Controller was trimmed down to the example on the right (click for larger view):

I’ve created a fully-working example on GitHub if you’d like to download it and play.

So the question at hand: Is the class labeled “Clean Example” preferable (ie, better)? First, let’s explore how I accomplished the “clean” View Controller. Then I’ll tip my hand on and share what I like about this approach…

EmailComposer

In order to accomplish the self-declared Clean View Controller above, I placed all of the configuration processes and the delegate method for the MFMailComposeViewController in a new class called EmailComposer. It should look familiar if you recall the previous example:

 1import Foundation
 2import MessageUI
 3
 4class EmailComposer: NSObject, MFMailComposeViewControllerDelegate {
 5    // Did this in order to mitigate needing to import MessageUI in my View Controller
 6    func canSendMail() -> Bool {
 7        return MFMailComposeViewController.canSendMail()
 8    }
 9    
10    func configuredMailComposeViewController() -> MFMailComposeViewController {
11        let mailComposerVC = MFMailComposeViewController()
12        mailComposerVC.mailComposeDelegate = self
13        
14        mailComposerVC.setToRecipients(["someone@somewhere.com"])
15        mailComposerVC.setSubject("Sending you an in-app e-mail...")
16        mailComposerVC.setMessageBody("Sending e-mail in-app is not so bad!", isHTML: false)
17        
18        return mailComposerVC
19    }
20    
21    // MARK: MFMailComposeViewControllerDelegate Method
22    func mailComposeController(controller: MFMailComposeViewController!, didFinishWithResult result: MFMailComposeResult, error: NSError!) {
23        controller.dismissViewControllerAnimated(true, completion: nil)
24    }
25}

So literally, the only thing I did is

Cut the function definitions for configuredMailComposeViewController, and the MFMailComposeViewControllerDelegate method.
Paste them into the new EmailComposer class, which inherits from NSObject (a requirement for this particular delegate protocol’s conformity), and conforms to the MFMailComposeViewControllerDelegate protocol.
Adjust my View Controller to create an instance of EmailComposer , obtain a configured MFMailComposeViewController, and present it whenever the user taps on a button in my UI.

Conclusions

The View Controller in its final version is focused. It’s primary concern is presentation and handling of user interaction with the View itself, rather than needing to worry with configuring an MFMailComposeViewController and its delegate callback.
EmailComposer is less of a hassle to test, in the sense that I no longer need to instantiate a View Controller in my XCTestCase class just to test my MFMailComposeViewController stuff. It’s a real pain to test an actual View Controller instance, so I like that I can easily create an instance of EmailComposer and test away without the bulk.
No need to import MessageUI in my View Controller.

All in all, this is the cleanest, simplest, most balanced solution (that I could think of) to factoring out some logic to another class, so as to make my View Controller as clean as possible.

The goal was to make sure the appropriate responsibilities are assigned to the right classes. Presentation logic is all in the View Controller. Configuration and delegate callback implementation is done in EmailComposer.

I’m thinking through applying this same idea to other more complicated examples (UITableViewDataSource and UITableViewDelegate come to mind), and I think it would do us a lot of good to strategize on how to avoid making the View Controller the “catch-all” delegate / data source class for everything that’s currently on the screen_._

Hopefully these thoughts spark some ideas in the Swift community. This post has already been revised slightly based on feedback that I’ve received from folks on Twitter. If you have additional ideas in regards to choosing the right delegate, holler my way! I’d love to hear from you.

Thanks for reading.

Expanded Thoughts on Swift’s Type Inference

Thu, 21 Aug 2014 02:19:45 +0000

In my recent op-ed on clean coding in Swift focused on Type Inference, I began by saying,

Quick! Tell me! What is the Type of the birdDetails constant in this code example:

let birdDetails = birdDetailsFromStorage()

With no additional context to glean information from, the correct answer to the question is, “I have absolutely no clue…”

But is that concluding assertion true? Hmm…

I’m learning, and as I’ve weighed a recent Twitter conversation and thought on a comment thread that Rob Napier made on the post quoted above, I’m compelled to expand a little on my first post on Type Inference as it relates to clean code in Swift.

Something struck me as I read Rob’s comment: Why wouldn’t I know the Type that would be inferred from what is returned by birdDetailsFromStorage() and assigned to birdDetails? Presumably, I named the function what I named it intentionally. The part I missed, was that if I had designed well and created a Type called BirdDetails (say, a Struct as Rob proposed), then all of a sudden, an inference can be made by both the compiler and a human that the birdDetails constant is… well… an instance of BirdDetails. Imagine that!

To quote Rob (emphasis added):

Type inference should only be used when the result is unambiguous, but the best solution is to make the result unambiguous.

Bingo. The best solution is to make the result unambiguous. You and I as code authors are in charge of the clarity or ambiguity of our code – it’s up to us to make the results of our function evaluations unambiguous.

When I named the function birdDetailsFromStorage(), I heavily implied something about its return Type in the name. I even implied it in the name of the constant. I was expecting the return Type to be something that encapsulated whatever “bird details” are – I just didn’t realize it at the time (although it’s super obvious now)!

The very name of a thing sets expectations for you and the readers of your code. It’s our job to set ourselves up for that expectation to be fulfilled! Be predictable with the return Type of your functions for your own sake. A function signature should be such that when you run across birdDetailsFromStorage()in some piece of code, you are able to legitimately expect it to return a BirdDetails.

Using this predictable, convention-based approach to give humans the right clues about what the compiler is going to compute a Type to be makes Type Inference a totally legitimate language feature to embrace for the sake of your code’s clarity and simplicity.

I’ll leave you with a final quote from Rob’s comments:

Don’t go implying that you’re returning one thing when you’re returning another. If you must, then yes, explicit types are your punishment. 😀

Thank you Rob for your insight and feedback. You can read more of Rob’s work at http://robnapier.net.

Clean Coding in Swift – Type Inference

Wed, 13 Aug 2014 04:22:25 +0000

Quick! Tell me! What is the Type of the birdDetailsconstant in this code example:

1let birdDetails = birdDetailsFromStorage()

With no additional context to glean information from, the correct answer to the question is, “I have absolutely no clue…” Or is it?

“Not fair!”, you say. “In the real world, I’d have the ability to option-click and learn the type from a pop-up tooltip, or learn this information by inspection from Xcode’s utilities panel.”

Truth. We would. But… should we have to for an example like the one above? Could we have helped ourselves out a bit by being explicit about the type of birdDetails?

This was the question I asked myself as I set out to determine how and when I prefer to explicitly specify the Types of my variables and constants at declaration-time, rather than letting the compiler infer the Type for me.

Type Inference is powerful and convenient. It enables us to leave off explicit type specifications when we declare a variable or constant, leaving us with nice, terse, clean-looking code. But in reality, for examples like the one posed above, is clean-looking truly “clean code”?

From Apple’s documentation:

Type inference enables a compiler to deduce the type of a particular expression automatically when it compiles your code, simply by examining the values you provide.

The key phrase that stuck out to me was this: “Type inference enables a compiler to deduce the type of a particular expression…”. Humans are not compilers!

I don’t know about you, but I could use all the help I can get when it comes to figuring out simple things like the Type resulting from an expression. Sure, I could rely on the IDE, but in debugging, or in trying to simply read and understand what the intention of my code is when I come back to it sometime later, I want to focus on the code, not on pop-up tool tips or inspector panels.

For instances where deducing the type is not simple for a human to do (and I mean really simple), I’m getting to where I prefer to specify the Type up-front. We’re used to doing this in Objective-C, and I even do it in C# when using var would obscure things. When a language gives me the option to be clear about Types, I try to take advantage of that valuable language feature for all but the simplest of situations.

The Simplest of Situations

Let’s think for a moment about this so-called “simplest of situations”. I would define such a situation to be when the Type resulting from an expression can easily, at a glance, be inferred by a human being without assistance from an IDE. It’s all about context here, and for these simplest of situations, I love Type Inference.

Compare the following two lines of code:

1let birdDetails = "Swift"

and

1let birdDetails: String = "Swift"

In the example just presented, typing “: String ” to explicitly specify birdDetails‘ type is superfluous in my opinion (and I prefer not to be repetitively redundant when I can). It’s crystal clear that birdDetails in this example is a String.

However, in situations like the one at the beginning of the article where, by simply looking, I would have to answer, “I have no clue what the Type of this is”, my preference / proposal for your consideration would be to go ahead and specify the Type at declaration time. Consider:

1let birdDetails: (genusSpecies: String, commonName: String) = birdDetailsFromStorage()
2
3
4//... somewhere else in a Swift file far, far away ...
5
6
7func birdDetailsFromStorage() -> (genusSpecies: String, commonName: String) {
8    return ("Apus apus", "Swift")
9}

When I’m writing this the first time, I can spend the time looking up the function’s return Type and specify it when I declare my constant. It will make my life so much easier down the road.

Don’t stumble over the fact that birdDetails is a tuple type (String, String). The point is that the function could have returned anything, and it would still have been impossible for me to tell you what the Type of the constant was just by looking, had I not specified it upon its declaration.

Being explicit about the type in the declaration has great potential to immediately help us get our bearings around a particular set of code when we return to it after any length of time. And it seems to me that one of the principal goals of writing clean code is to help ourselves and our teams make sense of code quicker so that everyone’s happier and more productive.

Whew. That was a long-winded exploration of some things to think about when relying on (or avoiding) Type Inference in your own code. Thanks for reading!

Since publishing this op-ed, I’ve expanded my thoughts on Type Inference as it relates to clean coding practices in Swift. I highly recommend that this post be read and considered alongside my latest musings,which were heavily influenced by Rob Napier’s comments below.

Clean Coding in Swift – Functions

Thu, 07 Aug 2014 18:16:23 +0000

I’ve been thinking a lot about how the principles of clean coding (Bob Martin’s “Clean Code”) apply in Swift. How do I express clean code in this language? Conversely, how do I avoid writing cryptic code in Swift? What language features help me write clear and self-explanatory code and what language features present the potential for tempting me to write obscure code in Swift?

I am beginning a commentary series that I hope will encourage clean coding practice in myself and in the Swift developer community. Dialog on these topics is welcomed – I have not “arrived”, so please – help me help the Swift community for the better!

The first in the series is on writing clean functions in Swift. As it turns out, Swift provides some really great mechanisms for defining self-explanatory, clear-purposed functions. We’ll start by analyzing the features around naming functions and their parameters, and will conclude on thinking through function decomposition.

Function Names

Something that I really enjoyed about Objective-C was that while method names were often long and verbose, they were extremely descriptive. My code often read like a narrative, and I enjoyed that. Some may have hated it, but I found it extremely helpful in facilitating my recollection of a method’s intended purpose and the expectations around its argument requirements.

I do my best to think hard about the names that I give my functions, ascribing to them a name that is specific, targeted, and focused on the single “thing” that each one does. Nothing in Swift mandates that we leave the verbosity of Objective-C naming conventions behind. In fact, the exact opposite is true! One example is that swift intentionally provides us with the ability to add external parameter names so that we can be as descriptive as we need to be about the names of our functions.

Parameter Names

Swift’s external parameter names, in my opinion, are wonderful for helping write self-documenting code. They simply help guide my mind back to what a given function does and needs in order to do its job. Anything to help me get back in the zone is worth spending a few extra keystrokes on, especially since Xcode’s auto-completion assists me so well when calling functions with long signatures.

Apple recommends the following:

Consider using external parameter names whenever the purpose of a function’s arguments would be unclear to someone reading your code for the first time.

I would only add that sometimes, that someone “reading your code for the first time” is you. Not technically, of course, but think about this: Write some code, leave it, and come back to it some time later. Will it make sense? Will you immediately go, “Ah, I know what I meant there”, or will you do like I’ve often done and say, “WHAT in the WORLD was I THINKING??!?”.

Spending a few seconds on typing a few more words to save brain power and potentially more seconds/minutes some time later is a worthy investment. And if you work on a team, your teammates will appreciate the extra care you put in to providing as many hints as possible through inventing good names. Good naming includes parameter names. Why not take advantage of the fact that Swift provides you this opportunity to write self-documenting code?

Function Decomposition

In order to make sure our functions are doing “one thing”, we need to make sure that the statements within our function are all at the same level of abstraction. -Bob Martin, Clean Code pg. 36

This is just general advice without respect to a specific language. A couple of things to think about:

Watch out for key words like “and” / “or” in your function names. These red-flag words often indicate that your function is doing more than one thing and can be further decomposed. Consider:

1func washAndDryCar() {
2    // Logic to wash and dry a car
3}

A preferred decomposition could look something like this:

1func washCar() {
2    // Logic to wash a car
3}
4
5func dryCar() {
6    // Logic to dry a car
7}

Doing one thing can still involve multiple steps. But if each step takes a few steps of its own, that group of steps can be extracted out into another function. Consider:

1func washCar() {
2    // Pre-rinse code (example implementation - 4 lines)
3    // Soap code (example implementation - 5 lines)
4    // Rinse code (exmple implementation - 4 lines)
5}

A preferred decomposition might look something like this:

1func washCar() {
2    rinse(durationInSeconds: 25.0)
3    soapCar()
4    rinse(durationInSeconds: 60.0)
5}

What’s neat about the final result of the decomposition is that not only is my washCar function shorter and more readable (from 13 lines to 3 lines), but I got code re-use by making the rinse< function take a duration argument.

Hopefully these thoughts spark a few ideas in you. Constructive feedback is welcome! How are you thinking about writing clean code in Swift?