In this article, we will improve the code that goes within our data source methods to make it more meaningful, understandable, and maintainable, either for table views, collection views, or any other kind that we need.

Disclaimer: This content is not about any different way of working with data sources, but rather about enhancing the internal implementations of the existent good-old and well-known data source methods.

Three Simple Rules

All it takes to have cleaner data source implementations is to stick to these statements:

• Avoid formulas for calculating indexes
• Avoid magic numbers
• Always consider all the possible scenarios

Applying these small concepts is really simple, and has enormous benefits in terms of code maintainability.

Sections

The first step, and the most important one, is to think carefully how the information can be split into sections.

In a data source, sections allows us to define logical chunks of data. Then, it makes sense to group items that are alike and visually together into sections.

As a practical example, we can take a look at the following table view:

Here, we can think of 3 groups of items:

• Album Info
• Tracks
• Actions

⛔️ A Bad Implementation

First, I want to show you what the code looks like when we try to handle everything into just one section:

Obtaining the number of rows is complex. Getting the indexes for creating cells is complex. Delegating actions is complex. Everything is complex. And that's because calculating the indexes is complex.

The problem with this kind of approach is that while in our head it might make sense — because we designed it — one day other devs will have to modify this code, and that day, they are going to have a terrible time.

✅ A Good Implementation

The good news is that it's not that hard to refactor it. All we have to do is divide the data into meaningful groups that make sense, and use one section per group.

If we group our data like this, we will always obtain indexes easily:

• For sections that contain a single element — like Album Info— the number of rows is always 1, and the row index number is always 0, for that first and only element
• For sections that contain a collection of elements — like Tracks — , the number of rows is the count of elements of that collection, and each element is obtained by subscripting with the given indexPath.row

This way, we realize that calculating the indexes is simple, as it will never require any intricate or shady logic. This is the most important part of dealing with data sources. If you've achieved a good distribution of your information into meaningful groups, your data source code is already robust enough. Congratulations!

Enumerations

A little issue in this code is that we are still using hardcoded numbers for identifying each section. Because of that, if we wanted to alter the sections, either by changing the order, or adding or removing some, we would have to modify all these numbers manually. That would be a cumbersome and error-prone task. Let's fix it.

If we make the following association:

Section 0 → Album Info

Section 1 → Tracks

Section 2 → Actions

Then, we can use an enum with integer raw values to represent and identify these sections unequivocally.

private enum Section: Int, CaseIterable {
    case albumInfo, tracks, actions 
}

It is a good practice to define this Section enum as a private type inside the class that we are working with.

Now, each time we are given an indexPath.section, we can tell what Section it corresponds to, using the enum initializer:

let section = Section(rawValue: indexPath.section)!

This way, we no longer need to use magic numbers:

if section == .albumInfo {
 
   // do stuff

}

Switches

Last, but not least, it's a good idea to have a discrete way to switch over that enum we've just defined. This is, we will look for a way to consider all the possible scenarios regarding sections, never missing out any of them.

This is done very simply. We just have to use a switch statement — and avoid if-else chains — each time we have to identify a section in the code.

✅ Good

switch section {
    case .albumInfo:
    case .tracks:
    case .actions:
}

⛔️ Bad

if section == .albumInfo {
    
} else if section == .tracks {
    
} // other cases can be missed out easily

⚠️ Avoid Default

Since the number of elements that we have in the Section enum is finite, it is recommendable not to write the default clause. That way, we force ourselves and our teammates to always update the switch statements to still consider all possible scenarios whenever the sections get altered. Although having the default clause may look innocuous, it could be harmful, as it is an easy way to forget extra cases that might be added later.

️️⚠️ Define Limits

One little issue is that the Section(rawValue:) initializer returns an optional value. And it makes sense, as we could think of any number from the integers' domain, and it doesn't necessarily mean that there should be a valid section for that number.

Usually, our section numbers will go from 0 to sections.count — 1. This is, if we try to initialize a Section with a rawValue that is ≥ the amount of sections, we won't get a valid case for that number, then nil will be returned. Nevertheless, this scenario is not expected to happen, as we should always constrain the number of sections of the table view to equal the total number of sections we have defined:

func numberOfSections(in tableView: UITableView) -> Int {
    return Section.allCases.count
}

Outcome

Finally, this is the result of a clean data source implementation:

For further reference, you can check out this sample project.

Conclusions

As always, we must strive for clean code. It makes ourselves better developers, and our code more pleasant to work with for everybody.

Lessons Learned

• Sections: Divide your data into meaningful groups, one section per each
• Enumerations: Avoid magic numbers, use a Section enumeration
• Switches: Always prefer switch over if-else, and prefer not to use the default clause for finite enumerations

I hope it helps, and I look forward to see your comments and experiences below.

Happy data sourcing!

In this article, we will face a question that we should always ask ourselves when writing a function:

How should I name this function?

Although this question looks simple, getting it answered properly determines a crucial aspect in our professional lives as software developers. It makes our codebases cleaner and easier to use, as we will see.

The Importance of Clear APIs

If you were to use a function from a third party library, let's say for creating fancy labels, and you find these two options:

// A
static func makeLabel(withTitle title: String) -> FancyLabel

// B
static func configure(_ text: String) -> FancyLabel

Which one would you feel more comfortable with? A or B?

In case you are still hesitating, I'll give you a clue: common sense makes me think of option A, too.

Why option A, then…?

First, let's analyze why B isn't so good: Option B does not tell us what we are configuring exactly. Is it an existent instance? Does it create a new one? Does it return a new thing? It doesn’t tell us what's the meaning of the String it expects either. All we can tell beforehand is that it receives a String and returns a FancyLabel, but we don’t know exactly what it does. There is ambiguity and lack of information, and that's something we should avoid.

Option A, on the other hand, is totally explicit about these three things:

• What it needs in order to work — a title
• What it does* — it makes a label
• What's the outcome — the created label

* We care about what it does (or is supposed to do), not about how it does that thing. We don’t care about the inner workings of the function. That’s how encapsulation works.

The usage of this function becomes very natural by just having these three things clear, because in this way we can know what the function goes about, without misunderstandings. As simple as it.

We will see it clearer when we take a look at how these functions are called:

let labelA = FancyLabel.makeLabel(withTitle: "Hello world") // clear

let labelB = FancyLabel.configure("Hello world") // not so clear

Now, what if we translated that example to a real life project with multiple developers working on it? What would you prefer to name your functions like? A or B? What would you prefer your teammates to name their functions like? A or B?

You can think of it like this: Each time you define a function, you are defining an interface that someone else will use in the future. Even if it’s private, and even if you think that nobody else will ever use it, it's always important that it is clear. Because any developer at any moment could need to deal with the internal code of any class in the project, even yourself. You never know!

In conclusion, if you put effort on naming your functions such that there is no ambiguity about what their inputs and outputs are, and what they do, a lot of effort can be saved when others have to call your function. They won’t have to go through its implementation to figure it all out. In this way, we save time and avoid misapprehensions that can lead to bugs. Defining clear interfaces in our code comes with the huge benefit of a codebase that is easier to deal with, to use, to shape, and to maintain.

Those extra seconds — or minutes — you need to think of the name of a function is time well invested.

Function Signatures in Swift

One of the most radical changes in Swift, if we compare it to Objective-C, and particularly since Swift 3.0, is the way function signatures work. Since that version, Swift is not only less verbose than its predecessor, but it's also clearer.

Let's take a look at an example:

dateLabel.text = [formatter stringWithDate: [[Date alloc] init]]];

dateLabel.text = formatter.string(with: Date())

We see two main differences here. First, the creation of the date instance is way more verbose in the first case, although that's only related to Objective-C's verbosity. Then, we can observe that the Objective-C version, besides lots of extra brackets, includes an extra word (Date) that the Swift one doesn't have.

This subtle — yet effective — change is actually possible thanks to the static nature of types in Swift. In the Swift version of the function, you are not able to pass in another object that is not a Date, because the compiler won't let you do that.

This change is simple, but it opened doors to a new world of function signatures. The code in general has become much more pleasant to read, as it's more concise and more similar to spoken language.

As mentioned, our next step is aiming to prune functions signatures, in such a way they become short enough to be concise, but still clear enough to avoid ambiguities.

Pruning

Finally, let's analyze some examples of different functions signatures and see how we can make them look better by pruning, i.e. by removing some words.

// Signature

func moveView(view: UIView, toPoint point: CGPoint) { ... }

// Usage

moveView(view: headerView, toPoint: .zero) // ⚠️ long and redundant

It can become:

// Signature

func move(_ view: UIView, to point: CGPoint) { ... }

// Usage

move(headerView, to: CGPoint.zero) // 👏 clear and concise

Thanks to static typing, we don't need to specify that we are moving a view object in the function signature. Since the function requests for a UIView object, the only thing you can pass in is a that kind of object. Same with the point.

There are exceptions, though. You still need to specify what the parameter is about because its type might not be enough to describe it.

// Signature

func makeButton(withTitle title: String) -> UIButton { ... }

// Usage

let button = makeButton(withTitle: "Function Naming") // 👍 good

Let's see what happens when we try to prune here…

// Signature

func makeButton(with title: String) -> UIButton { ... }

// Usage

let button = makeButton(with: "Function Naming") // 👎 not clear

This happens because the type (String) does not exactly match the semantics of the content (a title). A String can represent lots of other things besides titles.

When in such a situation, there are two possible approaches that we can take. We either specify the semantics of the content by making the parameter name more explicit, as in the first part of the example above, or, we create a new type that describes the semantics more specifically, and use that new type as a parameter. In the example, we could have created a Title type for managing titles. The ideal scenario is going with the latter, as you will take even more advantages from the static typing system and your code will end up being more secure. I recommend you learn about techniques like phantom types and tagged types for this purpose.

Final Thoughts

• Naming is hard. However, the time you spend on doing so is well invested. It reduces the possibilities of misunderstandings and prevents other developers — or yourself — from having to look at how all the code works trying to understand what it does. So, invest time in naming.
• Take advantage of static typing. Make your APIs clear and concise.
• Share this knowledge with your teammates and encourage good practices.
• Practise! Practise! Practise!

And remember, a function should always be clear about 3 things:

• What it needs — input
• What it does — describe the process without exposing the inner workings
• What it returns — output

See you next time!

I hope this guide is useful for you, and I look forward to learning about your experiences and opinions in the comments below. Please, comment, suggest, and if you find it useful, share :)

Thank you for reading.

Follow us on social media platforms:
Facebook: facebook.com/AppCodamobile/
Twitter: twitter.com/AppCodaMobile
Instagram: instagram.com/AppCodadotcom

If you enjoyed this article, please click the 👏 button and share to help others find it! Feel free to leave a comment below.

Function Naming in Swift was originally published in AppCoda Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

I wrote this article almost two years ago. Unfortunately, the website where I published it shut down. By luck, though, I've been recently told I was allowed to republish this content, which is what I'm gladly doing right now.

Special thanks to Brujo Benavides who pushed so hard on getting these contents back to the Internet. Soon, I will revive some other articles I wrote, which are worth the respawn too. Stay tuned.

This blogpost in particular contains lots of time references, so, when it says "2 months ago" it now means "21 months ago", "recently" now means "a while ago", and so on… You get the point. Anyway, it is kind of irrelevant when it happened. The important part, which is what I'd like to revive, are the lessons that I learned during this experience. So, here we go…

Back then in November 2016 …

About two months ago, I attended the Try! Swift NYC conference and the Brooklyn Swift Developers meetup, and since then, my life as a software developer changed radically.

It’s almost impossible that I can pass on all the things I learned back then, so that won’t be the goal of this post. However, I’d like to channel, at least, a bit of all the excitement and good vibes that I’ve been feeling.

Going To Conferences ✈️

Recently, I’ve been asked the following question several times:

"Why going to conferences if you can watch the talks online?”

This comes up mostly because of what it takes for us in Argentina to afford all the expenses.

Well, that’s mostly what I’ve learned: Going to conferences and meetups is not just about learning technical stuff. You also meet new people, you make new connections, you get to know different mindsets, and learn different ways of thinking. You also have fun. You also end up with new ideas. You also change. And by changing you grow, in your personality and in becoming a technical expert. And a big list of etceteras, which can all fit in this fact: YOU LEARN ABOUT LIFE.

Of course, all of this depends on you: you have to be open to these kind of experiences; otherwise, they won’t happen. Anyway, if you just start by being open and keeping a good attitude overall, the rest will just happen and everything will flow at some point: it’s nature.

What Meetups Can Do 🗣

About five months ago, I started to organize Swift meetups in Buenos Aires. At that moment, I had no idea what a meetup represented, and I didn’t know what meetups could do for us. The only thing I knew was that “you meet other fellows and share knowledge”. Of course that happens, everyone ends up learning new stuff. But, besides that, I can guarantee that meetups have power. If you put energy into it, it will be spread, as simple as that.

During our first event in June, two talks were given, and we began meeting each other in this local community. The feedback was great, and I was quite excited about it.

Later, in September, we held our second event, and the outcome was awesome. Even more excited people than the first time and three speakers, with whom I kept in contact after the event: I gave them my good feedback about how everything went, and their feedback to me was gratifying too. All of this made me want to go on with it.

Besides the stuff overall, I also learned that little things can make the huge diference. For instance, in his talk, Francisco Depascuali mentioned an app for a charity project he was working on: Proyecto Alimentar. For non-spanish speakers: it’s about a community whose commitment lies in reducing the contradiction between people wasting food and the need of other people for it, i.e. turning that wasting into helping.

Getting to know these kind of things really motivates you; everyone learns from each other, yet it’s not only about the technical knowledge.

With results like these, you feel thankful, happy; but most important, you feel empowered to do more and more things that can help the community and, why not, the world. At the same time, you feel successful in your career path. Give and take. It’s about life.

We Are Sowing 🌱

Everything we sow today is tomorrow’s harvest. Somehow, we are leaving a mark. If we want to live in a better world, we have to strive for it.

One thing I’ve realized is that spreading good messages pushes people towards success. And, of course, everything depends on what kind of success we are talking about. Individually, I’m talking about growth and personal fulfillment. As for communities, I’m referring to collective development and general well-being. I hope that’s the success most of us look for.

In relation to what I mentioned above, meetups and conferences are a great place for these things to happen, and it’s really good to know that. This is mainly why I’m writing today. If you have participated in these kind of events, you will probably know what I’m talking about. If you haven’t, it’s never too late: I encourage you to do so, you’ll experience the benefits by yourself. If you want it, go for it.

Balance ⚖️

I’ve just talked about meeting people and getting involved in communities. Enhancing your social skills does contribute to your Career Path. But, what about your technical skills?

It’s worth mentioning the importance of maintaining a balance between your technical and social skills. When you look at the big picture of yourself as a professional, these two complement each other. To be one day an architect or lead developer, you wouldn’t be complete if you’re pure technical, in the same manner you wouldn’t be complete if you’re just social either.

Mentors, Not Idols 👨‍🏫

Finally, I want to stand out the importance of having mentors. Not only in your professional career, but also in every aspect of your life.

Mentors are people from whom you learn, people who inspire you, people who motivate you to grow. Nevertheless, they do not escape from the fact that they are just that: people. They are humans; ergo, not perfect. They make mistakes, as you do. They learn, as you do. They can be really good at certain things, and really terrible at others, as you are. Be aware of that: Always remark the good aspects of every mentor in your life, and take the best of them. You would not want to be like someone _at all_. You might want to acquire someone’s knowledge and/or ways of thinking in certain aspects of your life. This is the best way of being yourself: choosing, prioritizing, and being selective, always being guided by your principles.

Again, mentoring is a give and take. Without realizing it, you might be mentoring some people in some aspects of their lives, too.

Further Reading 📚

A lot can be discussed on these topics, but this article ends here. If you enjoyed it and are eager to read more, below you’ll find a list with some related resources that might be of your interest. Thank you for reading.

• Healthy Minds in a Healthy Community — How communities can be a good place for helping and being helped.
• Come Together — The outcomes of meeting people face-to-face instead of virtually.
• The Secret Life of a Digital Nomad — Great talk on escaping from your comfort zone and some advices you have to keep on mind while doing so.
• A Retrospective on Try! Swift NYC 2016— A summary of how it felt attending this conference.

Thank you for reading.

The Power of Meeting People was originally published in Tech Lead Talks on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Strategy Pattern is one of the first design patterns I’ve learned in the theory. Sadly, however, it was very difficult for me to find real use cases where it could be applied in actual iOS codebases. Most books and tutorials showcase examples that are good for understanding what the pattern goes about (by using everyday objects such as animals, vehicles, or pizzas), but are usually far away from the actual code that you encounter in your projects.

In this article, I will expose concrete scenarios that I've recently stumbled upon while developing some iOS apps, and in which I could find the pattern to be an elegant solution that successfully led the code towards improvement.

A Real Use Case: Followers List

The Scenario

A social network app. I needed to add a screen that would show a list of all the current user’s followers. This screen also needed some complex functionality such as pagination and filtering followers by certain search criteria. The point was that a very similar screen already existed, but this one would show trending users instead of followers.

The Regular Solution

The first solution that would usually come to my mind was trying to reuse that existing view controller's code by making some differentiation within it, like:

enum UserType { case trending, followers }
var userType: UserType! // set from the outside

var users: [User] = []

// and at some point in the view controller...

switch userType {
case .trending:    
    users = retrieveTrendingUsers()
case .followers:  
    users = retrieveFollowers()
}

I'm over-simplifying the code from the actual code for readiness purposes. Of course, there were more complex stuff like users being fetched asynchronously (I had to use completion closures instead of direct assignation), etc... But these things don't matter for the purpose of the example.

The problem with this approach is the switch statement inside the view controller: It's a code smell, and I will explain you why. Let's suppose that in a near future, we are requested to add a Users that I'm following screen to the app, and it has the exact same functionalities that these two we are handling above. In that case, we'd need to add an extra case to both the enum and the switch statement. Now imagine a further future where we were requested to add more similar screens that only vary on how the users are fetched: We'd end up with a huge switch statement with lots of cases and we'd have to modify the view controller each time we need to add a new one. That doesn't sound right. Wouldn't it be better if we could make the view controller independent of this retrieval process? Couldn't we find a place in the code where the view controller can say "OK, I know I need to fetch users here, someone else will give me these, I don't care where they come from. I just know how to display and filter them."?

A Better Approach

Let's define an interface for fetching users, which is the process that we want the view controller to be independent of:

protocol UsersStore {
    func retrieveUsers() -> [User]
}

class TrendingUsersStore: UsersStore {

    func retrieveUsers -> [User] {
        // returns trending users from server
    }

}

class FollowersStore: UsersStore {

    func retrieveUsers -> [User] {
        // returns current user's followers from server
    }

}

Finally, let's have the view controller compatible with this interface:

var usersStore: UsersStore!

// somewhere in the view controller...

users = usersStore.retrieveUsers()

In the same way a certain userType was injected from the outside depending on the navigation (probably in a prepareForSegue function or similar), now the corresponding usersStore has to be injected instead.

// from somewhere else outside the view controller

controller.usersStore = FollowersStore()

What are the Benefits?

We have just gained a lot with this little change. Notice that we’ve eliminated the enumeration, and that we no longer need to break inside something (the enum and the switch statement) to add more code to handle variants. Now, if we were to add more ways to retrieve users, we could just add new classes that conform to the UserStore protocol, without having to modify anything. This is pretty much the open/closed principle, that you’ve probably heard of. Our view controller is now closed for modification (we don’t need to modify it whenever we need to add more similar screens), and our UserStore protocol is open for extension (we can add as many classes as we want conforming to it in order to have more and more ways for retrieving users).

Also, we are programming to an interface, not to an implementation anymore (that's something we've been told we should accomplish over, and over, and over). Notice that the view controller relies on an interface: it knows what should be done (users retrieval), it doesn't care about how it's done (whether it's by requesting followers to the server, or by requesting trending users to the server, or by fetching users from a local database, or by fetching hardcoded users from a test case, etc).

Speaking of which, this is a huge win for testability too. Given that how the users are fetched is not a responsibility of the view controller anymore, now we can inject it with fake users that we create in our test cases, and check whether or not these are displayed and filtered properly.

What’s more, our view controller is now smaller, as it has been taken away some responsibilities. By achieving this, we are following the single responsibility principle a bit more than before.

Other Use Cases

I've also come across other scenarios that I will briefly share below, so you can see how easy it is to find good opportunities to apply the Strategy Pattern in iOS apps:

• A feed that would show posts in different fashions depending on the user’s settings (e.g. dark mode). The seam here was the point in the code where the cells were formatted. Dark format, light format, among others, were turned into strategies (classes in this case) that conformed to a unique CellFormatter protocol.
• A screen that had to show messages (as in a chat fashion), but depending on the current user's type, the messages could be fetched in very different ways (hitting different APIs and parsing items differently). Even though the root problem here was clearly the API's design, changing it was not an option at that point, so, applying strategy for the messages retrieval client-side was a clever and practical solution to enhance the iOS app code.

Finally, I want to give you a magic formula to detect the usual suspects:

• Suspect from any view controller that is being reused in screens that are alike, but differ in some aspects, and whose code in charge of handling those differences is inside the view controller, and is not trivial. Watch out for switch statements (or worse, long if-else chains) that need to add more and more cases to handle variants.

Of course, there are other situations where the pattern applies as well. I just found this one involving ViewControllers' internal logic to be very repetitive among apps, and I have rarely seen the pattern already applied in these cases.

Conclusions

We should not force any design pattern to be applied at all costs. However, we've learned that finding scenarios where the Strategy Pattern does fit in iOS codebases appears more often than we think.

Applying the pattern is actually really simple, and it has huge benefits, as I mentioned above:

• Get rid of code smells like enums / switch statements that need to be modified frequently
• Program to interfaces and not to implementations
• Follow the Open/Closed Principle
• Facilitate unit tests through dependency injection
• End up with shorter classes by following the Single Responsibility Principle

This story is published in Noteworthy, where 10,000+ readers come every day to learn about the people & ideas shaping the products we love.

Follow our publication to see more product & design stories featured by the Journal team.

• Follow our publication to see more product & design stories featured by the Journal team.

Usually, they report the bug, and, when it’s your turn to fix it, the first thing you think is “Okay, I’ll put a breakpoint where the alert is created and see what’s going on”. Next step, you’re doing something like this:

To find out that the reason could just be:

A server error! Your code might look different, though. Maybe you are not even parsing server errors as Error objects in your code (you should), but follow me on this one… When this is the case, couldn’t we all save a lot of time if we knew beforehand that the issue was caused by the server, and not by the client app?

What if the alert view itself could describe what's going on?

This way, testers would be able to see that information without needing any developer debug it.

Of course, this debug information shouldn't reach final users. But that is not difficult to achieve, as we'll see next… Introducing: debuggable alerts.

UIAlertController+Debug

We can introduce a simple mechanism to append debug information to our alerts in an extension of UIAlertController :

extension UIAlertController {

convenience init(title: String?, message: String?, error: Error? = nil, enableDebug: Bool = Settings.shared.enableAlertLogs) {
        var finalMessage = message ?? ""
        if enableDebug, let theError = error {
            finalMessage += "\n\n⬇ DEBUG INFO ⬇\n\n\(theError)"
        }
        self.init(title: title, message: finalMessage, preferredStyle: .alert)
        let ok = UIAlertAction(title: "OK", style: .default) { _ in
            self.dismiss(animated: true, completion: nil)
        }
        addAction(ok)
    }

}

Notice that I distinguished between the scenario where we want debug messages vs. the one where we don't. We should not display any debug information in AppStore builds: these messages are meant to be internal and should never reach final users.

In this example, the default value for the enableDebug boolean is loaded from our application's shared settings, and from there, it can be automatically set depending on the build configuration, as I explain in this article about how to switch our app's settings in an efficient way.

Also, an Error instance should always be passed to the alert's initializer, so that the debug information can be obtained from there when needed.

Said that, this is how you would initialize the alert:

case .failure(let error):
    let alert = UIAlertController(title: "Oops", message: "Feed could not be loaded.\nTry again later.", error: error)
    present(alert, animated: true, completion: nil)

As you can see, since the enableDebug parameter takes a default value, you don't even need to bother passing it through the initializer's call, that's done behind the scenes for you.

Of course, any iOS dev involved in the project should always leverage this custom initializer instead of the default one when creating an alert. But that’s about a practice that is not difficult to get used to.

The Outcome

Now, let's compare what the process was like without debuggable alerts…

1. QA can’t load feed, error says “Could not load feed. Try again later”
2. QA reports bug to PM
3. PM creates associated ticket and assigns to an iOS dev
4. iOS dev takes the ticket and starts debugging
5. iOS dev finds out the cause was actually the server
6. iOS dev notifies PM about it
7. PM reassigns ticket to backend dev
8. Backend dev grabs ticket and fixes issue

… to what it is with debuggable alerts:

1. QA can’t load feed, error says “Could not load feed. Try again later. 500 server error”
2. QA reports bug to PM
3. PM creates associated ticket and assigns it directly to a backend dev
4. Backend dev fixes the issue

See the difference? The debug message is something really small, but it has a huge impact on the process. No iOS devs were required to take a look at the issue in the latter scenario. No time and effort wasted. Lots of context switches avoided. This kind of situation happens more often than what you think. So, why not using something that simple to our projects that could benefit us like this?

In Conclusion

By introducing this subtle practice, we can make a big difference by saving time and effort in our everyday work. Also, the whole team becomes more efficient and in consequence is able to deliver results faster.

In this article, I just exposed the example of the “500 server error” because I consider it being maybe one of the most annoying to mobile devs. However, the benefits of using debuggable alerts also apply to several other scenarios where having some little debug information about the error can help a lot by pointing out where the problems could be, without having to manually debug.

Happy coding!

Introduction

Engaging gears in a project involves powering up our everyday processes. In the iOS world, a very important one is how we deal with environments and other settings that need to be customized depending on the audience. Xcode does have a set of tools to help us along the way. Unfortunately, though, I've seen that most of the times teams are not even close to take the best of these tools. It's not their fault: I think Apple doesn't do very well at encouraging good practices, as they just provide not-so-useful configurations by default.

In this article, we'll explore how we can take advantage of Xcode configurations, and how we can define our app's settings in an organized way.

Xcode Configurations

The way Xcode can package different settings into your builds is through configurations. Roughly speaking, a configuration is just a bunch of settings that define how the compiler must create the build. The IDE lets you customize some settings depending on the different configurations. You've very likely seen these:

Debug vs. Release

These are the two configurations that Xcode gives us by default. Of course, you can create your own, but this isn't a common practice since there aren't universal conventions adopted by the iOS community about which configurations could be useful to have depending on the project.

These two default configurations have several differences, which I'm not going into detail here, but can be summarized in:

In a debug build, the complete symbolic debug information is emitted to help while debugging applications and also the code optimization is not taken into account (faster build times). Whereas, in release build, the debug info is not emitted and the code execution is optimized (slower build times).

As for their usage, debug is the configuration we normally use in our everyday life, whereas release is what we use to distribute our apps to other people: testers, project managers, customers, the world.

The point is that, these two are usually not enough. What's more, devs often mislead ≪debug vs. release≫ with ≪staging vs. production≫, concepts that should not be mixed up.

We can do better

Some projects work with different environments: development, staging, production, pre-production, etc. Take whatever you want. This classification doesn't have a natural connection with the two default configurations we've discussed above. Even if we tried to force this correspondency, it wouldn't always work out very well. For instance, if you want to prepare a release build, it doesn't mean it should point to a production server: Take the situation where you have to prepare a release build for QA which needs to be tested against a staging server. Default configurations just won't work.

In consequence, I propose replacing the basic debug & release configurations by others that could help us a bit more. To keep it simple, I'll only include staging and production environments in this approach, but you'll observe that it's very easy to add more environments as you need them.

Let's redefine configurations

We can define these 4 configurations instead:

• Debug Staging
• Debug Production
• TestFlight Staging
• TestFlight Production

By just reading their name, you might have guessed what they are about. Here are the details:

• The first two of them (Debug Staging & Debug Production) behave as the original Debug configuration, but each one points to a different environment.
• Something similar happens with the last two (TestFlight ones). They behave as the original Release one, including compiler optimizations and excluding debug information, but each one works on its corresponding environment.

You should end up with something like this:

The Fifth Element

There is a reason why I chose to call the release configurations “TestFlight” instead of “Release”. There might be certain events in your code that need to happen only when the app is used by final users, not by testers or customers. A clear example is the usage of analytics to track events. It could be a requirement that event tracking should only be applied to final users, not to testers under production environments. In this case, we are talking about a TestFlight Production configuration with some subtle differences, hence the need for a distinction. Introduce our fifth configuration:

• AppStore

This configuration can be quickly duplicated from TestFlight Production. Notice that you won't always need it, as you could not have to perform anything different than when on TestFlight Production.

Now, you might wonder how you can manage different things to happen in your app depending on the selected configuration. That's explained in the next section.

Custom Settings

There are many ways to achieve what we need: Perform different actions based on which configuration is selected. There are precompiler directives, environment variables, different plist files, and more. Each one has its pros and cons. I'll just focus on the way I use to do it, which I consider a very clean one.

Those different actions that need to be done depending on the configuration can usually be encapsulated into variables, which will define our app's behavior. These variables are usually called settings. Example of settings are: the server's API's base URL, the Facebook App ID, the logs' detail level, whether or not offline access is enabled, whether or not to show debug information in alerts, etc.

Next up, I'll show you the way I currently manage custom settings to vary depending on the selected configuration, which I consider a very convenient approach so far, based on my experience.

Settings.swift

The app's custom settings can be easily accessible through a singleton.

struct Settings {

    static var shared = Settings()

    let apiURL: URL
    let isOfflineAccessEnabled: Bool
    let feedItemsPerPage: Int

    private init() {
        let path = Bundle.main.path(forResource: "Info", ofType: "plist")!
        let plist = NSDictionary(contentsOfFile: path) as! [AnyHashable: Any]
        let settings = plist["AppSetings"] as! [AnyHashable: Any]
        
        apiURL = URL(string: (settings["ServerBaseURL"] as! String))!
        isOfflineAccessEnabled = settings["EnableOfflineAccess"] as! Bool
        feedItemsPerPage = settings["FeedItemsPerPage"] as! Int
        
        print("Settings loaded: \(self)")
    }

}

This struct is in charge of reading and storing the settings (that we'll later define in the app's Info.plist file) so that they are available from anywhere in the codebase. I prefer to perform force unwraps here since if a setting is missing, I don't want my app to run.

Info.plist

We will define our settings in the Info.plist file. I recommend using a separate dictionary entry to group them all:

So far, we have set up a clean way to retrieve our app's settings. However, they don't vary among configurations yet. We're almost there.

User-Defined Settings

Let's think. What things normally change depending on the configuration in any project? Well, there is the compiler optimization level, there are the header search paths, the provisioning profiles, and much more. Wouldn't it be nice if we could define our own custom things-that-vary-upon-selected-configuration? Well, it turns out that we can, by creating User-Defined Settings.

Since your User-Defined Settings may have to live together with others that you haven't created, it's recommended that you use a prefix convention to name yours.

Now, to refer to one of these from the Info.plist file, you just do it like this:

$(YOUR_USER_DEFINED_SETTING_NAME)

Integrating them all

This is where the magic occurs: You can replace all the fixed strings from the Info.plist entries that correspond to your settings with their corresponding references to each User-Defined Setting. You will need one User-Defined Setting for each custom setting that you have.

When the Info.plist file is compiled, it'll take all the settings values that correspond to the selected configuration, and these will be fixed on each entry at compile time.

Now, you can nicely refer to any setting from anywhere in your code like this:

if Settings.shared.isOfflineAccessEnabled {
    // do stuff
}

Finally, selecting which configuration to compile with is a piece of cake, either from Xcode:

Or from CLI:

Wrapping Up

By using this approach, we have gained these benefits:

• Organized builds workflow.
• Organized way to manage app's custom settings.
• Flexibility to change settings depending on the configuration.
• Easiness with continous integration (given that selecting which configuration to compile with is easily doable in command line tools).

However, there are some caveats that are worth the mention:

• There is no flexibility to change settings at run time, as they are packaged with the build at compile time.
• Switching often between configurations is not that nice: Xcode creates a build from scratch each time you change the build configuration, which means having to wait for the entire project to recompile in that case.
• Settings can only be modified through the .xcodeproj; there is no flexibility to change their values nicely from the outside.
• User-Defined Settings are exposed to anyone that has access to the code, so it's not a recommended place to put any key.

These pitfalls can be solved, though. The aim so far was just to improve our usage of these tools when coming from an almost zero-knowledge base. Mitigating these issues implies applying some modifications that complicates things a bit further, and they are out of the scope of this article, as I didn't want it to become too overwhelming. But believe me, we’ve done a lot. In an upcoming second part, we will explore how to face these issues and take our projects to the next level…

To be continued.

📝 Read this story later in Journal.

🗞 Wake up every Sunday morning to the week’s most noteworthy Tech stories, opinions, and news waiting in your inbox: Get the noteworthy newsletter >

Hello there!

It’s been a while since I shared Getting the right colors in your iOS app, a blogpost I wrote for helping iOS devs prevent the color nightmare that happens every now and then. That blogpost was cool and got more visits than I expected, but, the information I exposed at that moment was neither complete nor certainly accurate, and it got outdated very quickly too. My appologies for taking too long to write about it again.

Today, I bring this update in order to help the iOS community once more, because, I found that there aren’t much articles out there that involve all the required information that one needs in order not to fail miserably when working with colors in Xcode.

After lots of research, information gathering, experiments, insights, and conclusions, I feel prepared to dive in to the colors world again. So, here we go…

How do I set the right color?

First things first. There are two ways of setting a color for a UI component in Xcode:

• Interface Builder
• Programmatically

No matter which one you use, the point is that, you need to make sure you obtain the same exact color in either case, even more if you consider that it’s very likely you’ll need to use both methods at some point in your project. Consistency is key.

It turns out that when you create a color programmatically, by calling UIColor(red:green:blue:alpha:), Xcode will create a color using the sRGB IEC 61966-2-1 color space (more on color spaces later). Given that case, whenever you are setting a color through Interface Builder, you must ensure that it's being created with that same color space too, so that, the color is exactly the same.

This is, given this code…

let myCustomColor = UIColor(red: 38/255.0, green: 49/255.0, blue: 197/255.0, alpha: 1.0) // sRGB

…you should make sure that you set the same RGBA values and you use the same color space when in Interface Builder…

You can quickly verify that the colors are the same by doing this simple experiment:

1. Put a view inside a view
2. Set the outer view’s color programmatically
3. Set the inner view’s color via Interface Builder, using the same RGBA values, and selecting the sRGB color space
4. Build & Run, and check out the outcome

Well done! This is half of the process of being consistent, and it might have already solved your issues. However, in order to guarantee that the colors in your app match the UI designs you are supposed to follow, you must also make sure that the color you’ve picked is the one you’re supposed to use, and this is the hardest part, which I’ll cover in the next section.

How do I pick the right color?

Extracting the RGBA components of a color can be a cumbersome task, and this could be mostly because of a lack of understanding of how color spaces work. Long story short, I will try to summarize this complex world as best as possible.

In order to represent a color, two components are required:

1. Values
2. A color space, in which the color is represented ← This is what most people don’t know

On to the values, there are several models to depict them:

• RGBA (Red, Green, Blue, Alpha) ← the one we mostly use in Xcode
• HSV (Hue, Saturation, Value)
• HSL (Hue, Saturation, Lightness)
• And more…

These different models are just bells and whistles to work more comfortably when creating colors through UI sliders or fancy wheels, and I won’t get into detail here, since you’ll encounter yourself copying RGBA values about 99,99% of the time. It doesn’t matter whether you use 0–255 integer notation, 0–1 floating point notation, or Hex notation; it’s all the same as long as you do the maths well.

Now let’s talk about color spaces, which is where it does get complex…

Color Spaces

What’s a color space, anyway? Do I even need to care? The answer is yes, at least a bit.

A color space is a component that defines which range of colors can be represented through the notations we mentioned above.

The human eye can see plenty of colors. In fact, it can see way more colors than what most screens can actually expose. This is because the hardware that screens use is somehow limited, and in consequence they work with restricted color spaces (at least more limited than what the human eye can see).

Different screens represent colors through different color spaces, depending on the device’s hardware.

• All iPhones prior to iPhone 7 only represent colors within the sRGB IEC 61966–2–1 color space (sRGB for short)
• Whereas, newer Apple devices, such as the iPhone X, use a bigger color space that covers a wider gamut of colors, the Display-P3 standard (or, just P3 for short)

If you click here you’ll see an image that contains a logo, which you’ll only distinguish if your display works with a P3 color space (otherwise, you’ll see a boring rectangle filled with just one reddish color).

Now that you understand what color spaces are, let’s explore the issues that they carry…

How color spaces fit into RGBA values

Let’s suppose we are using the RGBA notation to write down a color. With this notation, and a depth of 8 bits per channel, you can represent up to 255 x 255 x 255 colors = 16,581,375 (the famous 16 million colors) and even more, when you combine them with the alpha component (x 255 again) you’ll get up to more than 4 billion (also known as true color). That is the amount of colors you can represent using this notation, and notice that this value is fixed. It doesn’t matter whether you choose a bigger or smaller color space to work with: You cannot represent more than that number of colors in RGBA. Imagine this as having a fixed number of 4,228,250,625 slots: Any color you want to represent must fall into one of these slots. Notice this: You won’t necessarily get a bigger number of colors by using a bigger color space, because there is a limit on how many colors you can write down. What changes, however, is that when working on a bigger color space, the variation between two consecutive values (for instance: #A0A0A0 and #A0A0A1) is more noticeable to the eye. This happens because when using a bigger color space, more actual colors have to fit within the same amount of fixed slots. Besides, when in a bigger color space, the values on the extremes will represent more vivid colors (e.g. #FF0000 in P3 is a much more vivid red than #FF00000 in sRGB). It's because of these observable changes that you probably get headaches when not getting the exact color you want: Maybe you are just obtaining their RGBA values from one color space, and generating them in Xcode using a different color space. If the color spaces mismatch, you will get incorrect colors in your app, in spite of having replicated the same RGBA values.

Now that you know that color space matters, you must make sure that you pick colors from the proper color space. This is, if you are using sRGB to represent a color in your app, you must pick colors from a sRGB color space, and just replicate the same RGBA values in Xcode. This sounds a lot simpler than it really is. The million dollar question is, how do you pick a color from a sRGB space?

Getting the right RGBA values

Photoshop

If you are cropping your assets right away from a PSD file, then it’s a piece of cake: You just open it in Photoshop and use the eyedropper tool to get the RGB values. This way, you will get RGB values with a full alpha component (A = 1). If you want to be more thorough, you can check out the individual layer components (for instance, a color overlay) and take the exact RGB and Alpha values (transparencies might play an important role in your app’s design). But, be aware: The PSD file must be opened using the sRGB color space as its working space. You can check that out by going to Edit > Color Settings. If it’s not using sRGB, you will need to convert the file to that profile, and it’s highly suggested that you warn the designers to use sRGB profiles when creating assets for mobile apps.

There is another option, though. You can get the color from a different profile, say Adobe RGB for instance (which is bigger than sRGB), and generate the colors in Xcode by always using the Adobe RGB color space, both via Interface Builder (by selecting it from the dropdown menu) and via code (by using a different function to generate the color, other than the conventional UIColor(red:green:blue:alpha:) that I mentioned above - you can check out the official documentation on how to do that). However, sRGB is the standard that most applications use (e.g. web navigators, Sketch, Zeplin, etc, not to mention Xcode itself too), that's why I highly recommend sticking to this one.

Other Design Apps

If you are getting your assets from tools like Sketch or Zeplin, you can get the RGBA values straight from there, without even needing an eyedropper tool. These values are represented in the sRGB color space.

Digital Color Meter

Another simpler approach to extract RGB values is to use an eyedropper tool from your Mac. There is the native Digital Color Meter app that can do that. The problem with this one is that, if your iOS app needs to use a bigger color space than the one that your display works with (for instance: you are using P3 for your app, but your Mac’s display is limited to sRGB), then the eyedropper won’t catch those P3 colors that your sRGB display cannot represent. To prove that, you can check out this image, and use Digital Color Meter to extract its RGB values while working in a sRGB display. You’ll always get the same RGB values across the whole image. On the other hand, if you open it in Photoshop (using P3 as working color space), and use the eyedropper tool, you’ll realize that there are two different colors in the image, even though you won’t be able to distinguish them through your sRGB display. I have discovered this through lots of try-and-error-like experiments. Another issue with Digital Color Meter is that you have to make sure that the image is opened with an app that takes into account its embedded color profile. Preview app works well for this purpose. Another experiment led me to realize that picking a color from an image opened in Preview vs. picking the same color straight from Finder’s carousel preview (which does not embed the profile) lead to different RGB values.

What about image assets?

Besides picking individual colors properly, you must make sure to pick files properly too when working with entire images. As stated by the official documentation,

Apply color profiles to your images. The default color space on iOS is Standard RGB (sRGB). To ensure that colors are correctly matched to this color space, make sure your images include embedded color profiles.

To know which color profile is embedded into an specific image, right-click the file and check it out under Get Info. To embed the image into a different color profile, you can use tools like Photoshop.

Shouldn't I work with P3?

Now you might wonder, if the newest devices can display P3, why should I stick to sRGB? Well, the truth is that if you work in a computer that has an sRGB display but you need to cover P3 colors, you’re going to have a hard time. Currently, almost at the end of 2017, most designers still work with sRGB displays. This is, they won’t be able to get the best out of their assets if they work with a bigger color space than what they can actually see on their screens.

Apple recommends to use the P3 color space only in specific situations, such as for UI components that can enhance the user experience by standing out through more intense colors, or for entire pictures that need to be more vivid. This WWDC session has a great insight on when to use P3.

The transition hasn’t been done yet, and again, sRGB is still the standard today, so, that’s the choice you should go for in most of cases.

TL;DR

As you might have noticed, working with colors may look like a very straightforward thing, but it isn’t, at all.

Nevertheless, it’s just a matter of consistency. My suggestions to keep this process as simple as possible are:

1. Let the UI designers know that you are going to work with the sRGB color space. Suggest them to use the sRGB color profile for mobile apps. Make sure the PSD files you use to crop images have sRGB as working space, and the PNG images you use in your assets catalog have the sRGB color profile embedded.
2. Use UIColor(red:green:blue:alpha:) for creating colors programmatically.
3. Make sure the sRGB option is selected in the Interface Builder’s color picker dropdown menu each time you set a color this way.
4. Work efficiently: Stick to one source of truth.

Bonus Track: The One Source of Truth

I’ve been wondering for years how it was possible that there hadn’t been a way to refer to the same thing when getting a color from the code vs. from Interface Builder. How come I have to write these RGBA values twice for the same color? I mean, one time in my code, and another time in Interface Builder’s color picker. Not only this is an obvious pain in the neck, but it also leads to problems because of breaking the DRY principle.

Good news, as of Xcode 9, you can create a color specifying it only once, by using Color Assets.

I got mind blown when I saw this tool for the first time, as not only it prevents you from writing things twice, but also organizes your app’s colors in such a way that is very convenient for everyone to use. Honestly, I shouldn’t have been that surprised, as this kind of utility should have existed from long, long time ago.

Bad news, this tool is only compatible as of iOS 11. So, if your app has to support older iOS versions, you will need to write this kind of code:

let lime: UIColor

if #available(iOS 11.0, *) {
    lime = UIColor(named: "Lime")!
} else {
    lime = UIColor(red: 222/255.0, green: 254/255.0, blue: 50/255.0, alpha: 1.0)
}

…

Resources

I hope I’ve just covered this topic well and I made it understandable using the right words. There is a lot more detail to dive in. I will be happy to see your comments and experiences!

Here is a list with some of the resources I’ve used during my research. They could be useful for you too:

• https://www.youtube.com/watch?v=N2T62ZHIu6s
• https://developer.apple.com/videos/play/wwdc2016/712/
• https://developer.apple.com/videos/play/wwdc2017/821/
• https://developer.apple.com/documentation/uikit/uicolor
• https://developer.apple.com/ios/human-interface-guidelines/visual-design/color/
• https://petapixel.com/2009/09/17/why-you-should-probably-use-srgb/
• http://appleinsider.com/articles/16/09/09/apples-wide-color-screen-on-the-iphone-7-will-lead-to-more-faithful-color-reproduction
• https://apple.stackexchange.com/questions/252159/what-color-space-is-iphones-7-wide-color-display-p3
• http://martiancraft.com/blog/2017/06/xcode9-assets/#color-assets
• https://blog.zeplin.io/asset-catalog-colors-on-xcode-9-c4fdccc0381a
• https://webkit.org/blog-files/color-gamut/
• http://www.astramael.com/
• https://en.wikipedia.org/wiki/SRGB
• https://en.wikipedia.org/wiki/DCI-P3
• https://en.wikipedia.org/wiki/HSL_and_HSV

Happy coloring!