Op-Ed on Andrew Bancroft

Agile Blogging

Fri, 21 Nov 2014 01:58:04 +0000

After I wrote my post on 7 Reasons You Should Write About Swift, I began to think about some of the roadblocks that hinder blogging.

Blog Blockers

I started to think about some of my own reservations about blogging, and boiled it down to a couple of big blockers:

Time
Perfectionism

My problems with blogging in the past often came down to the fact that it takes time, and that if was going to publish something, it had to be perfect.

Of course, every one of us is time-bound, and every one of us has the potential to improve, no matter how “perfect” we think we’ve made something.

It’s interesting to me, because these issues come up in software development a lot, and one of the tools that much of the software development community has embraced are “Agile” practices for software development.

I really enjoy many of aspects of Agile (Scrum being the specific flavor of Agile practices that I’ve had experience with), particularly as it relates to enabling the rapid delivery of a useful product that satisfies my customers, and the ability to adapt to change and make iterative improvements on that product.

Agile Blogging

I began to think, “What if some of the things that I enjoy about Agile could be applied to my blogging routine?” How could that positively impact my experience, so as to motivate me to blog more and remove those road blocks that hindered me before?

If I had to pick two key phrases from what I like about Scrum that could apply to blogging, they’d be “rapid delivery of a useful product” and “iterative improvements”.

Rapid, because what I really want is to produce useful content quickly. (Notice I said “useful”, not “perfect”.) And that’s where “iterative improvements” comes into play. Since anything I publish will always have the potential to be improved, it makes better sense for me to prioritize publishing something that has potential to be useful, with the mindset of cycling back around to improve that publication later over time.

Getting Practical

Over the past several months, I’ve been working to set blogging goals for myself using Agile principles to help me meet those goals and improve my content over time. Here’s how I, personally, get pragmatic with Agile blogging:

Set a goal

Without a goal, I find it very easy to not blog, even though I enjoy it.

My goal right now is simple but sustainable: I shoot for producing one blog post a week.

Block off time

I set aside chunks of time throughout my week to blog. Each time block is about 30 minutes in duration. To produce a post that I’m pretty satisfied with (ie, it’s useful and contributes something meaningful to my audience), I use about 2 to 3 of those time blocks per week, but almost never all in one sitting.

Write, publish, improve

My first-priority goal with each post is to get across that main point as clearly as possible. After a quick proofread, I schedule version 1.0 to publish.

Of course there are going to be mistakes with that initial publish. I almost immediately circle back around and view the live post, noting areas of potential improvement. If I still have time in my 30-minute block, I make the improvements I can and publish them. If I don’t, I wait until my next blogging time-block, and make the improvements then.

Since no post will ever be perfect, I work to make things as useful and meaningful as possible, minimizing error as best I can, of course. Sometimes feedback from my readers helps me find places where I can improve. I value that feedback, and often bump that advice to the top of my priority list for a given post. The point is that I write, publish, then improve iteratively.

Examples and supplementary content

I write a lot about programming, and there are often times where a post could be enhanced with an example. I try my best not to pressure myself to build everything for version 1.0 of the post. If I think a full-fledged example that someone can compile and run on their own machine would enhance things and provide additional value to my content, I’ll usually add that “feature” to a post after the initial version in most cases.

Doing it this way does a couple of things for me:

It lets me get the main substance of the post out there sooner.
It provides an opportunity to inform folks on my social media outlets one more time about the post, along with the enhancement.

Summary

Blogging with Agile in mind has been a significant help for my motivation to blog and has served to keep me on track with my one post a week goal. My hope is that by sharing how Agile principles have impacted me, you, too, will be inspired and empowered to start creating great content for us to enjoy! Happy (Agile) blogging!

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?

Contributing My Share of Bytes

Mon, 04 Jun 2012 03:16:33 +0000

There is a lot to know. A lot.

I happen to be one of those individuals who gets geeked out very, very often over very, very nerdy things.

As of late I’ve been really wanting an outlet to share what I’ve learned / am learn_ing._ The world doesn’t need another blog detailing the same things that are already out there – at least not a verbatim copy of information that’s available already.

But the thing I’ve figured out is that everybody has a slant on how they glean understanding on something that’s unique to them. I can’t tell you how many times I’ve read multiple blogs full of code or with a perspective on an idea and sort of used the combination of them all to come up with a better understanding on ___ topic that ends up working for me.

I recently read a tweet from Scott Hanselman
here that caused something to just click in my mind: he encouraged blogging rather than emailing. This makes sense – emails and other forms of direct communication have limited potential for helping effect. A blog post and an email with a link to the blog post has much greater potential for impact.

And then I took that and theorized about what could be possible if I just had an outlet to share what I’ve run across, because you never know when you might have the answer someone was looking for – they just needed you to share it in your own unique way that spoke to their particular scheme of processing information.

So here’s to hoping that maybe possibly somehow someday someone will find something of interest somewhere in this blog of mine. For now i foresee posts about some of the following:

Thoughts on code that I’m learning / writing
Stuff about SQL Server and Business Intelligence
Discoveries from other realms of study
Tutorials on things I’ve figured out and think might help someone someday
Thoughts / reactions / responses to news
Who knows what else…