Use semantic naming on iOS
As a tech oriented company building its own digital platforms, we at OpenClassrooms need to carefully make choices when it comes to building an app. When we built our iOS app, we decided early on that every visual component would be named semantically. I very much hope that you want to learn more about semantic naming because I brought a special guest who knows better than anyone else what it’s like to be named semantically.
Don’t be shy, talk to him. I assure you he’s a nice component, one of our first and most loyal! He never causes us any problems.
Reader: Hey buddy! What’s your name?
Cute Purple Button: Hello, my name is Primary Button.
Reader: Wow, that’s certainly uncommon. Does the rest of the OpenClassrooms code make fun of your name?
Primary Button: Actually, it’s quite the opposite. It is a very common name at OpenClassrooms and it brings a lot of peace between us, visual components.
Reader: A lot of peace? Are you not always causing trouble to each other?
Primary Button: No and my name actually helps a lot! Especially because I am an OpenClassrooms fanboy who always wears the latest t-shirt! As a result, not that long ago, before the OpenClassrooms rebranding, I was bright orange, many would have certainly called me Orange Button. Imagine all the hate I would have gotten from pretty much the entire code if I had renamed myself Purple Button! I am telling you, I am glad to be named Primary Button and proud that my look doesn’t depend on anyone but me.
Reader: You sure look like a proud button. I still don’t understand why you’re named Primary Button. Could you not be named Mario or Luigi?
Primary Button: Although I do like these names a lot, they wouldn’t really help my developers, would they? My name reflects my purpose which is to pursue the main scenario flow of a given use case. I am the button that users should press on a screen, that’s what my name says anyway.
Reader: You definitely are a proud button, thanks for the introduction!
What is semantic naming?
It’s abstraction. It’s to name components after their purpose instead of their appearance. The appearance is an implementation detail and the superview shouldn’t know or worry about it. It’s no different from naming UserGateway, a component that makes the connection with the User data stored in CoreData. You don’t name it UserCoreDataGateway or you hide behind an interface. Your business logic shouldn’t know or worry about CoreData, it’s an implementation detail.
Colors, fonts, assets, views. Every visual component can and should be named semantically. A color is not red, it’s error or danger. A font is not Arial, it’s title or caption. An asset is not left-chevron-icon, it’s back-icon.
Benefits of semantics naming
Semantic naming provides the same benefits as abstraction does for Object Oriented Programming. It reduces code dependency which makes the code easier to maintain.
It enforces design consistency. Let’s say you work on a screen to let a user edit their profile. It will obviously have a save button somewhere. As a developer (or designer), it feels right to use a button named Form Validation Button while you would have to check other screens to know if Purple Button is the one to use.
It brings quality, everything is here for a reason, and there is no randomness. A color is not chosen because it felt beautiful at time, but for its purpose.
Although these benefits are real, they are somewhat generic and I can’t measure their impact on OpenClassrooms app. Fortunately I have a concrete example. Recently, OpenClassrooms rebranded. We had to change the design of everything including the iOS app implement our new visual identity. From a development point of view, and thanks to semantic naming, it took us less than a week to have the rebranded design merged into master. The git stats looks pretty good:
162 files changed, 1,003 insertions(+), 1,127 deletions(-)Once broken down, the stats looks even better:
- ~90 of the files changed were simple assets updates such as fonts, illustrations. The app icon represents ~40 files on its own, that’s quite a lot.
- ~50 of the updated files were on screens with a design heavily based on illustration like the splash screen or our authentication screens. They had an illustration as a background that required some coding to be replaced by a plain background color.
- ~15 of them were project files and random nib updates to remove fonts that should have never been in the nib files in the first place.
- The remaining 5 files were configuration files that define the semantic names of our typographies and colors across the whole application. Some changes in a few configuration files and the whole app already had a brand new look. The semantic naming shined here.
Dark mode, which increasing numbers of users are requesting, is another great opportunity for the semantic to shine. It would require nothing more than adding extra configuration files.
Semantic is hard
It’s actually as hard as cache invalidation, in the words of Phil Karlton:
There are only two hard things in Computer Science: cache invalidation and naming things.
Naming a component Primary Button or Danger Color is much harder than naming it Purple Button or Red Color. It gets even more complicated when you realise that the #d3d3d3 color from your design specification matches multiples semantic colors in your code.
To be done correctly, semantic naming needs to be embraced by your UX and UI designers. Without a semantic mindset from the UX and UI engineers, you will often find inconsistencies and fix them somehow with unsatisfactory semantic names. Semantic starts with UX/UI, but they unfortunately have their own issues.
From what I see, as an iOS developer, our UX and UI friends don’t have the right tools to do semantic design. Designers can easily create a style guide to define that an error is red. But once they design, their app won’t enforce the semantic since they will apply colors as hex values. Their frameworks such as Material are too generic which prevents them from having a semantic naming. I really like how Material named most of its icons though.
Last but not least, as iOS developers, we cannot abstract everything. If your primary button change from being 16 points away from the screen edges to a fixed width, then ultimately, the parent view will have to change some constraints in order to adapt to this change.
While semantic naming makes the code easier to maintain, we remain dependent on designers. I will, once again, take the rebranding project as an example. During this project, the update of the teaser screen is the one that required the most effort, for a final result that looked like a downgrade:
The reason was simple, I couldn’t change the color in the code because the orange tone was a part of the illustration. Illustrations needed to be updated, which requires design work which is hard to obtain during a rebranding project where designers are busy and under pressure. Updating the illustration alone, however, would not have been enough to match our new visual guidelines.
Two versions later, once the designers were free from the rebranding deadline pressure, we were finally able to update the screen to this beauty:
What’s next?
When we started our iOS app and decided to go for semantic naming, we knew that it would bring us the Dark Mode for free and that it would require little more than adding a configuration file mapping some colors to some semantic names. We didn’t realize how high the quality of the semantinc naming need to be for a free Dark Mode. As for now, we are not ready for it.
The next step is to keep improving our semantic naming. Although we do have various ongoing actions such as team design review that helps us on the subject. We could also consider Dark Mode an opportunity to improve. What I mean is that if we add a Dark Mode feature now, we will certainly increase the workload of the whole team, and likely doubling that of our designers. It doesn’t seem right, does it? We tend to be problem solvers. If a Dark Mode becomes an issue, we will fix it, and it is even easier when we already know that the solution is to step up our semantic naming until we are so confident that we no longer have to worry about that bright and dark colors. The only time we should ever worry about that colors is when we introduce new semantic names, which should be pretty rare anyway.
For more on that subject, I recommend you Introducing Dark Mode, an Apple video from the WWDC 2018 in which they describe how Mac OS developers should handle the Dark Mode feature on Mojave. Spoiler: Use semantics!
TL;DR
Semantic naming is abstraction. It is a principle that we implement on the OpenClassrooms app. It brings us design consistency and makes the app easy to change design-wise; it notably allowed us to rebrand the entire app in less than a week. However, naming components is a hard task, it requires time and the participation of the UX/UI designers to be done correctly. The Dark Mode feature is a great way to assess semantic naming as it should be costless for both developers and designers.
