DEV Community: Cihat Gündüz

Laser Focus priority strategy

Cihat Gündüz — Mon, 27 Sep 2021 14:03:47 +0000

Have you ever worked on a bigger change for an app and struggled with the release schedule? Have you ever wanted to get feedback from users early but weren't sure when exactly the right time is? Here's a simple but effective prioritization technique that can help slim down your scope and give you more confidence in it with different stages that can be mapped to Alpha, Beta & Release.

There are lots of prioritization techniques that aim to solve different problems. You've probably already used some form of value vs. effort-based prioritization techniques, such as RICE. Maybe you've even asked your target audience with a purposefully designed survey to learn from them, e.g. using the KANO model. Every prioritization technique has its use cases and maybe they already helped you make a lot of useful decisions.

But these strategies are designed for a higher-level kind of prioritization, as in deciding if you should be implementing feature A or feature B first or if feature C is even needed in the next version at all. They don't scale down to tasks or even sub-tasks of your features though, so it's quite possible to do too much within a specific feature. Also, they don't help answer when you can start putting the feature in users' hands for early feedback to apply user-focused approaches, such as the Lean Startup methodology. One could of course opt for a method that is independent of scale, like the MoSCoW method, but their categories wouldn't be easy to rate because they're so abstract that different people would have different expectations for each category.

The goal of the Laser Focus prioritization strategy I suggest in this article is to provide clear rating categories, help with task scopes and provide an easy to apply method for interpretation. All three aspects together help you stay laser-focused.

Laser Focus categories

There are three goals we want to reach with our categories:

Decide which tasks are in the scope of the currently planned release.
Prioritize tasks needed for an Alpha or Beta version higher than the others.
The Categories names should have an actionable, self-contained meaning.

We're suggesting the following categories which fulfill all requirements:

Vital

Absolute minimum needed for the first round of testing. Can be ugly.

This allows for shipping a product with just "Vital" features or tasks implemented to a small group of testers to get feedback early. Of course, the scope of this Alpha testing should be made clear stating what basic features or tasks are still missing so they are not unnecessarily reported by the testers. But the vitals of the product or feature can be tested already and we get a first round of feedback if we're headed in the right direction.

Essential

Core aspects required for basic functionality. Can have rough edges.

A second and bigger round of testing can be started as soon as all "Essential" features or tasks are implemented. At this level, no specific testing scope needs to be communicated, it should be enough to call the version a "Beta" version where the base features are available but still a lot of things are missing or incomplete.

Completing

Ironing out rough-edges and completing aspects of functionality.

The "Completing" level defines the scope where the final product is ready to be released. In some situations, e.g. if a new version was announced for a specific date, the product can also be released while still, some "Completing" tasks are open, but then it should be publicly marked as "Beta". Typically this level includes all kinds of features or tasks that are important for a bigger customer base but are not relevant to evaluate the core of the product.

Optional

Nice-to-haves that can be delayed to later (versions) or skipped entirely.

The "Optional" level has the notion that the features or tasks rated as such are wanted things, but that they are in no way necessary to release a finalized version of a product, even long term. Hence they can also be easily delayed or scrapped if needed as per the resources of the team.

Retracting

Nice-to-haves (at first sight) that can (potentially) cause more harm than improve things.

Unlike "Optional", features or tasks rated as "Retracting" should be actively avoided. That means it can make sense to document or keep them somewhere including the rationale why they should be avoided for long-term decision making. This saves time when the same idea comes up again sometime in the future. Also, if multiple people are involved in the rating, it can help identify the tasks where discussion might be necessary to clarify the effect of a task on the product.

Laser Focus matrix

The second pillar of the Laser Focus strategy is its multi-dimensional scalability. To explain what this means and why it is important, let's apply the categories we have so far with an example: Let's develop a stopwatch app to track time for different things done throughout a day. This is the initial list of feature ideas, rated using the Laser Focus categories:

Create projects → Essential (essential to app, but pre-filled projects enough for first test)
Edit projects → Completing (not a necessity for testing purposes, but for final release)
Delete projects → Completing (cleanup task, not needed for testing purposes, but for final)
Start/Stop a timer → Vital (core idea of app, vital part of the app)
Select a project for the timer → Vital (without selecting project, app idea not fulfilled)
Edit past tracked times → Retracting (V2 with competitive feature, risk of cheating)
Delete past tracked times → Optional (nice to have, no risk of cheating as no added time)
Show historical time tracked on a selected project → Essential (core use case for app)
Show projects with the most tracked time → Essential (core use case for app)

Thanks to the categorization, we can already exclude two features from the first release and recognized even a feature we should probably never implement (6) that should be permanently documented. But more importantly, we now know that 4 and 5 are the "Vital" features to implement first. Let's start working on their sub-tasks:

Start/Stop a timer → Vital
1. Design Start/Stop button layout (low fidelity)
2. Design Start/Stop button coloring & icons (high fidelity)
3. Design Start/Stop button pulsating shadow effect (animations)
4. Implement Start/Stop button layout (low fidelity)
5. Implement Start/Stop button coloring & icons (high fidelity)
6. Implement Start/Stop button pulsating shadow effect (animations)
7. Setup basic tracked time database models
8. Persist Start/Stop actions into the database
Select a project for the timer → Vital
1. Design project selector navigation & layout (low fidelity)
2. Design project selector shapes, colors & icons (high fidelity)
3. Design project selector navigation & layout (low fidelity)
4. Design project selector shapes, colors & icons (high fidelity)
5. Persist selected project into the tracked time database model

All clear, let's get started, right? Right?

No. I'm sure you noticed it already while reading/skimming through them. There's a problem. We have prioritized the features thinking about what's really necessary for being testable, for putting the app into users' hands. But now we have the same problem again, just on a different level. These tasks (and potentially also their sub-tasks) aren't all "Vital" for our very first version to put in users' hands. How can we fix this? Should we apply another rating for the tasks, too?

Yes, absolutely! This is actually a requirement in the Laser Focus strategy: Apply the rating on all levels down the road! Not necessarily above levels, where you are allowed to choose any alternative prioritization technique. But the lower levels from wherever you want to start from should all be rated like this. Let's assign the Laser Focus categories to the tasks, too and then see what this means for overall priority:

Start/Stop a timer → Vital
1. Design Start/Stop button layout (low fidelity) → Vital
2. Design Start/Stop button coloring & icons (high fidelity) → Completing
3. Design Start/Stop button pulsating shadow effect (animations) → Optional
4. Implement Start/Stop button layout (low fidelity) → Vital
5. Implement Start/Stop button coloring & icons (high fidelity) → Completing
6. Implement Start/Stop button pulsating shadow effect (animations) → Optional
7. Setup basic tracked time database models → Essential
8. Persist Start/Stop actions into database → Essential
Select a project for the timer → Vital
1. Design project selector navigation & layout (low fidelity) → Vital
2. Design project selector shapes, colors & icons (high fidelity) → Completing
3. Implement project selector navigation & layout (low fidelity) → Vital
4. Implement project selector shapes, colors & icons (high fidelity) → Completing
5. Persist selected project into tracked time database model → Essential

It's important to note that the reference value for the ratings of the tasks was the feature because it's the direct parent. This means that I asked myself the question "Is persisting Start/Stop actions into database vital or essential to the feature Start/Stop a timer?" and not to the app or anything else. This makes answering the questions much easier.

Let's visualize these two different levels of rating with a simple matrix. On the X-axis we put the ratings of the features. On the Y-axis the ratings of the tasks. The circles represent the tasks:

As you can see, tasks 4a, 4d, 5a, and 5c are in the bottom left field, the "Vital-Vital" field, or short "VV". The field's background is tinted red. It contains all tasks the focus should be on first. Once they're all implemented, the very first testing round can begin, the Alpha phase starts.

The tasks 4g, 4h, and 5e in the yellow-tinted field "Vital-Essential" or short "VE" should be tackled next. Once all tasks in all three yellow-tinted fields are completed, the Beta phase starts.

The "VC" field with its "Completing" tasks for the "Vital" features should be tackled last among the tasks we defined so far. Once all tasks in all green-tinted fields are done, it's Release time.

In the above example, we skipped the tasks for all non-Vital features. If we had rated them also, the full matrix could have looked something like this, including also the "Retracting" rating:

We can see how the Alpha, Beta, and Release tasks are circularly layered around the origin point (bottom left corner), visually providing us a priority for each task based on its distance to the origin. This easily scales to a third axis if for example sub-tasks were added to each task. Formally speaking, this scales to any number of dimensions. To calculate the overall category of any given element, just look up all ancestors and just select the lowest priority as the overall category of the "atomic" (lowest level) element. For example, imagine a sub-task with the category rating "Essential", a parent task rated "Vital" and its parent feature rated "Completing". Overall, the lowest priority is "Completing", so this is the overall category of the sub-task.

Calculating the overall category alone can lead to many tasks being on the same level, especially at "Completing" where we have 5 different fields. A way of prioritizing features or tasks within the same category is by calculating the average of its own category combined with that of all its ancestor's categories. To do this, let's assign each category a number (from 1 "Vital" to 5 "Retracting"), the lowest level (e.g. a sub-task) can then be represented by a tuple, e.g. (2, 1, 3) in the above example. The average of these numbers is simply calculated by (2 + 1 + 3) / 3 = 2.0. Another task with more ancestors and the same overall "Completing" category might be rated as (3, 2, 3, 1) and therefore have an average of (3 + 2 + 3 + 1) / 4 = 2.25, so it should be prioritized lower. The higher the overall average, the lower the priority – that makes a lot of sense as the average number roughly resembles the distance to the origin – the highest possible priority.

But don't worry, you don't actually have to calculate these averages, there's a simpler way based on the matrix we've seen above with enough precision:

The above diagram shows in which order the fields should be tackled, based on origin distance. Note that there are two fields placed 2nd, 4th, and 5th each. For these fields, there's a choice to be made that can be different depending on the situation: Should we focus more on adding more features? Or should we focus more on improving the already started features? For a feature focus expansion first, you should continue in direction of the "Feature category", e.g. "EV" before "VE". For improving existing features first, it should be the other way around.

Laser Focus breakdown

In the above section, we learned that categorization on multiple levels is key to the Laser Focus concept. If you try to apply this to your project right away, you may realize though that many or even all of your features or tasks are actually "Vital" or "Essential" to you. If this is the case, then it's a sign that you have probably not efficiently split your tasks yet.

That's why it's important to break down your tasks the right way before categorizing them. The guiding question you should ask yourself while splitting features into tasks or tasks into sub-tasks should not be restricted to "which steps do I need to make to finalize it". You should also think about the effort for each step and if the effort isn't negligibly small, you might want to consider splitting it away. Sometimes it might seem to be hard doing that, but more often than not, it's a good idea to follow the approach "make it work, then make it better" while splitting the tasks.

For example, for the above feature "Start/Stop a timer" we could have split it up into 3 tasks: "Design the Start/Stop buttons", "Implement the Start/Stop buttons" and "Persist data". The problem with this is that there are no different levels of completion. It's better to break it down even further. Of course, we could do that as sub-tasks under these tasks, but to make priority calculation easier, it is recommended to do it in fewer levels. So instead we opted for "Design the Start/Stop button layout", "Implement Start/Stop button layout" and the same two tasks also for "... coloring & icons" and "... pulsating shadow effect".

Ask yourself which parts have their own effort and split them so each task is worth being prioritized based on the effort needed. Don't split micro-tasks away, it's not worth prioritizing such small tasks, just keep them as part of another task.

A proper breakdown is very important for the Laser Focus strategy to be effective.

Summary

Let's sum up the Laser Focus prioritization strategy:

Break down your features and tasks into smaller steps of different completion levels
Rate them on each level with "Vital", "Essential", "Completing", "Optional" or "Retracting"
Visualize or calculate the overall priority for the lowest level by considering all ancestors

Apply these steps at any given time for your project and it will help you keep focusing on the important things and confidently putting your work-in-progress versions into users' hands early.

I hope this helps!

_This article was written by Cihat Gündüz

Git Merge vs Rebase

Cihat Gündüz — Thu, 01 Jul 2021 13:22:23 +0000

An FAQ that explains and answers when to use which and why.

There's a common discussion among developers about how teams should use Git to make sure everyone is always up-to-date with the latest changes in the main branch. The typical situation this question arises is when someone worked on a new branch and then once the work is done and ready to be merged, the main branch had changes in the meantime in a way that the work branch is outdated and now has merge conflicts.

Obviously, they need to be resolved before the work branch can be merged. But the question is: How should this situation be resolved? Should we merge the main branch into the work branch? Or should we rebase the work branch onto the latest main branch?

In my opinion, there's only one correct answer to this question. From my experience, the main reason why so many discussions arise around this topic is that there's a lot of misunderstandings out there about how merge and rebase differ from each other in this context and a general lack of understanding, what a rebase even is.

So I created an FAQ for my team which tries to clarify things. Let me share:

What is a `merge`?

A commit, that combines all changes of a different branch into the current.

What is a `rebase`?

Re-comitting all commits of the current branch onto a different base commit.

What are the main differences between `merge` and `rebase`?

merge executes only one new commit. rebase typically executes multiple (number of commits in current branch).
merge produces a new generated commit (the so called merge-commit). rebase only moves existing commits.

In which situations should we use a `merge`?

Use merge whenever you want to add changes of a branched out branch back into the base branch.

Typically, you do this by clicking the "Merge" button on Pull/Merge Requests, e.g. on GitHub.

In which situations should we use a `rebase`?

Use rebase whenever you want to add changes of a base branch back to a branched out branch.

Typically, you do this in work branches whenever there's a change in the main branch.

Why not use `merge` to merge changes from the base branch into a work branch?

The git history will include many unnecessary merge commits. If multiple merges were needed in a work branch, then the work branch might even hold more merge commits than actual commits!
This creates a loop which destroys the mental model that Git was designed by which causes troubles in any visualization of the Git history.

Imagine there's a river (e.g. the "Nile"). Water is flowing in one direction (direction of time in Git history). Now and then, imagine there's a branch to that river and suppose most of those branches merge back into the river. That's what the flow of a river might look like naturally. It makes sense.

But then imagine there's a small branch of that river. Then, for some reason, the river merges into the branch and the branch continues from there. The river has now technically disappeared, it's now in the branch. But then, somehow magically, that branch is merged back into the river. Which river you ask? I don't know. The river should actually be in the branch now, but somehow it still continues to exist and I can merge the branch back into the river. So, the river is in the river. Kind of doesn't make sense.

This is exactly what happens when you merge the base branch into a work branch and then when the work branch is done, you merge that back into the base branch again. The mental model is broken. And because of that, you end up with a branch visualization that's not very helpful.

Example Git History when using `merge`:

Note the many commits starting with Merge branch 'main' into ... (marked with yellow boxes). They don't even exist if you rebase (there, you will only have pull request merge commits). Also note the many visual branch merge loops (main into work into main).

Example Git History when using `rebase`:

Much cleaner Git history with much less merge commits and no cluttered visual branch merge loops whatsoever.

Are there any downsides / pitfalls with `rebase`?

Yes:

Because a rebase moves commits (technically re-executes them), the commit date of all moved commits will be the time of the rebase and the git history loses the initial commit time. So, if the exact date of a commit is needed for some reason, then merge is the better option. But typically, a clean git history is much more useful than exact commit dates.
If the rebased branch has multiple commits that change the same line and that line was also changed in the base branch, you might need to solve merge conflicts for that same line multiple times, which you never need to do when merging. So, on average, there's more merge conflicts to solve.

Tips to reduce merge conflicts when using `rebase`:

Rebase often. I typically recommend doing it at least once a day.
Try to squash changes on the same line into one commit as much as possible.

I hope this FAQ helps some teams out there. Like ❤️ it if you liked it! 😉

_This article was written by Cihat Gündüz

Primer on Regexes

Cihat Gündüz — Thu, 06 May 2021 10:28:16 +0000

In this post, I will try to give you a practical overview of Regular Expressions to teach you what they are, what they can be used for and a quick intro to how you can use them.

What are Regular Expressions even?

Regular Expressions (short Regexes) are Strings that work as a DSL (domain-specific language) to do some common tasks within other Strings. A DSL can also be subscribed as "a programming language within a programming language".

In the case of Regexes, the outer programming language can be any programming language that supports the String type, it just has to support Regexes. Nearly all popular programming languages support Regexes, which makes Regexes so useful to know. The inner language of Regexes consists of only String with some characters having a special meaning.

For example in the String ".*@.*\.com" the . means "any character", the * means "any amount of <whatever precedes>", together .* means "any amount of any character". Then we have a non-special character @, then again .* followed by \ which means "escape the next character and treat like a non-special character" so \. together reads like a normal . character without the special meaning "any character". Lastly, there's com which is just a set of characters without any special meaning. Overall this Regex is a simple matcher for any email address ending with .com and containing a @ somewhere.

What can I do with the "Regex DSL"?

NOTE: With Ruby installed (on Macs it's preinstalled), you can type irb to start an interactive Ruby shell to play around with the samples below.

There are three main functions that any Regex string can be used with:

1. `matches`

Given a Regex and another String, this function checks if the given String "matches" the Regex. This means if there's "any" part within the given String that matches the specified Regex, it returns true, otherwise, it's false.

For example in Ruby (where matches is called match? – ? is part of the function name):

/.*@.*\.com/.match?('harry.potter@hogwarts.co.uk')
# => false
/.*@.*\.com/.match?('queenie.goldstein@ilvermorny.com')
# => true

2. `captures`

Given a Regex and another String, this function can read substrings out of the given text which matches marked portions of the given Regex. The portions in the Regex can be marked via ( and ). They are called "capture groups".

For example in Ruby (where captures can be accessed on the Match object):

/(.*)@(.*)\.com/.match('queenie.goldstein@ilvermorny.com').captures
# => ["queenie.goldstein", "ilvermorny"]

3. `replace`

Given a Regex and a Template String, this function can automatically replace matches with a given String where even the capture groups can be referenced via $1, $2 or in some languages also \1 , \2, etc.

For example in Ruby (where replace is called gsub):

    'queenie.goldstein@ilvermorny.com'.gsub(/(.*)@(.*)\.com/, '\1@\2.org')
    # => "queenie.goldstein@ilvermorny.org"

What does the "Regex DSL" look like?

There's plenty of useful "cheat sheets" for this with great examples:

https://www.rexegg.com/regex-quickstart.html#chars

Regular Expression Examples

Generally, there's 5 different kinds of DSL components to understand:

1. Character/Group Modifiers (e.g. `*`, `+`, `{,}`, `?`)

The default "building" block of Regexes are characters. After each character, you can write a modifier that tells how many times the preceding character is matched. The following modifiers are available:

0 or 1 times:
? (example: a?b?c? matches all of a, ab, abc, bc, c)

1 time exactly:
No modifier (default)

0 to ♾️ times:
* (example: a*bc matches bc, abc, aaabc)

1 to ♾️ times:
+ (example: a+bc matches abc, aaabc but not bc)

X times exactly:
{X} (example: a{3}bc matches aaabc but not aabc, aaaabc)

X to Y times:
{X,Y} (example: a{2,5}bc matches aaaaabc, but not abc)

X to ♾️ times:
{X,} (example: a{2,}bc matches aaaaaaaabc but not abc)

The same modifiers also work on Groups (e.g. (abc)+) (see below for groups).

2. Custom Sets (created with `[` and `]`)

You can define custom sets of characters by listing them without any separator within brackets, e.g. for a set of the characters a, b, c and numbers 1, 2, 3 we would write [abc123]. This is then considered as "one character of this set", thus matching multiple of them need character modifiers as in [abc123]* or [abc123]{2,5}.

You can also use ^ at the beginning of a custom set to specify that you accept any character except the set you specified in the brackets, e.g. [^\n] to accept any character except a newline.

Characters of which you know are ordered right after each other like numbers or the Alphabet you can also use ranges by putting a - in between, e.g. [a-zA-Z0-9].

[abc123]{3,} would not match a, b, c, ab, but would match 111, abc

3. Predefined Sets (`\s`, `\S`, `\d`, `\D`, `\w`, `\W`)

The following sets (simplified) are already pre-defined and can be used directly:

\s effectively same as [ \t\n], reads "any whitespace character"
\S effectively same as [^ \t\n], reads "any non-whitespace character"
\d effectively same as [0-9], reads "any digit"
\D effectively same as [^0-9], reads "any non-digit"
\w similar to [a-zA-Z_0-9] (includes Umlauts etc.), reads "any word character"
\W similar to [^a-zA-Z_0-9] reads "any non-word character"

4. Groups (e.g. `(` and `)`, `(?<name>` and `)`)

Groups could be thought of like "words" or "sentences", they change the default building block, which is "character" for any modifier to a set of characters, or a "group". For example, writing abc* reads "one time a, one times b and any number of times c". If you want to write "any number of times abc" you do this: (abc)*. The abc is then considered one group and the regex would match the whole string abcabcabc.

Groups also allow for specifying different options to choose from. For this, you write a group and separate the different words via a | like so: (abc|def) – this reads "either abc or def" and would match both 123abc123 and 456def456 but not adbecf.

These capture some sub-portions of a Regex and assign them a number or name which then can be used to reference them in code or in replacement template Strings. Typically capture groups like in (.*)@(.*).com are used then referenced back via \1@\2.com or $1@$2.com (depending on the language).

It's also possible to give the groups names, e.g. (?<user>.*)@(?<domain>.*).com to reference back like in ${user}@${domain}.com, but these are advanced features which are implemented differently in different languages (and are missing in some).

5. Match Modifiers (`\A`, `\z`, `^`, `$`, Lookarounds)

By default, a match for a Regex, like abc is done like a contains method. But you can also specify that the abc string needs to be at the beginning or end of a given string or of a line. For example, the ^ in ^abc makes sure only strings with abc at the beginning of a new line match. This will match def\nabc but not defabc. The $ in abc$ makes sure there's a line-end after abc. Use \A and \z to match among the entire String (matching multiple lines).

Lookaheads & Lookbehinds are more of an advanced topic and useful mostly when you want to match that the beginning or end of your Regex does NOT match a given Regex. In most cases, Regexes with Lookaheads & Lookbehinds can be rewritten with Capture Groups, so you should try to write them as Capture Groups instead and only read about these if the other options don't work as Lookaround are CPU-intensive operations and also kind of restricted (e.g. they don't support most modifiers).

Here's a good place to learn about them:

https://www.regular-expressions.info/lookaround.html

Common Quirks and validating new Regexes

One common thing to consider is that . in most languages does not match the newline character by default. But it can typically be turned on with an option, in Ruby by specifying the /m at the end which stands for "make dot match newlines".

Also note that in every language there are different characters that are reserved due to how Strings work in them, for example in Ruby / needs to be escaped with \/, in Swift this escape is not needed but there you need to escape { and } with \{ and \}. These quirks are important to remember when copy & pasting Regexes written for other languages.

Generally, when writing a new Regex, I recommend using a website or tool with 3 features:

An option to add a sample String to match against.
A Regex cheat sheet visible right on the screen to look up things.
A live matcher for the regex you write among the given sample String.

The site I've come to use here is this (runs Ruby in the background) :

Rubular

How can I use Regexes in my projects today?

There's no need to wait until there's a good opportunity to use Regexes, you can simply lint your projects using Regular expressions (including Auto-Correction support) via AnyLint:

Flinesoft/AnyLint

_This article was written by Cihat Gündüz

Photo by Agence Olloweb

Safer Localization in SwiftUI

Cihat Gündüz — Sun, 19 Jul 2020 17:25:41 +0000

Now that we've seen many improvements to SwiftUI during WWDC this year, including a possibility to go full-SwiftUI even on App level (I consider AppDelegate deprecated now), I just started working on my first serious pure SwiftUI-driven app.

While most of the UI code I wrote was a lot of fun so far and I'm learning some tricks to deal with data management along the way, what I was very curious to see was if and how SwiftUI changes & improves upon the localization APIs as well. The examples I had seen so far from Apple and all the popular posts and guides were not really going into any detail there and it just looked like localization is somehow magically baked into the SwiftUI views.

And that actually turned out to be the case, at least simply specifying a view like Text("E-Mail") and putting the key "E-Mail" into the Localizable.strings file + providing different translations for other languages seems to just work.

Digging a little further into how this works, I quickly came across the type providing the magic here: LocalizedStringKey. SwiftUI views like Text accept instances of this type as their first parameter and because LocalizedStringKey conforms to the ExpressibleByStringLiteral protocol, one can use String literals like "E-Mail" in my example above and they are turned into instances of the LocalizedStringKey struct automatically.

Having a look into what other protocols the LocalizedStringKey conforms to, I found ExpressibleByStringInterpolation which is a protocol that was introduced in its new form with Swift 5 via SE-228. Until I saw how Apple used this protocol for localization, I did not know about its existence at all, but of course there was already an NSHipster article about it, which only undermines it's usefulness. Here's an example what it looks like on the usage side:

Text("Hello, \(name)") // => "Hello, %@"
Text("Last updated \(date, formatter: dateFormatter)") // => "Last updated %@"

While all these things make the new APIs much more readable and easier to use than the old NSLocalizedString APIs, they do share some of their biggest flaws:

There are no compiler checks to ensure a key is (still) available in localization files
There is no support whatsoever to keep keys consistent across languages
There is no autocompletion, leading to many misspellings & exact name lookups

I had already written about this in detail in my blog post Localization in Swift like a Pro last year, where I also presented a solution for these problems using my tool BartyCrouch which I had started back in 2016 and the amazing SwiftGen, which I can only recommend for any serious app project.

But the workflow was designed for Interface Builder and NSLocalizedString and while it does continue to work because you could simply pass NSLocalizedString objects into SwiftUI views (they also accept plain Strings), it didn't feel natural to the new way of things in SwiftUI, so I've started exploring new approaches here.

First, I checked if there's already a new approach by the SwiftGen contributors and found that there was already some discussion going on regarding the new LocalizedStringKey struct. But things have not settled yet and it will probably take a lot more consideration and experience to get the localization part right. I decided to skip the "no autocompletion" issue for now as that can only be provided by generated code.

But I tried to find a new way to improve on the other two issues and could quickly find a fix for the "consistency across languages" one as for that I could simply use some lesser known features of BartyCrouch:

I use this .bartycrouch.toml configuration file:

[update]
tasks = ["normalize"]

[update.normalize]
paths = ["Shared/App/Resources"]
sourceLocale = "en"
harmonizeWithSource = true
sortByKeys = true

[lint]
paths = ["Shared/App/Resources"]
duplicateKeys = true
emptyValues = true

Note that Shared/App/Resources is the path my .lproj folders are within, including the Localizable.strings files.

Then I configured this build script above the "Compile Sources" step:

if which bartycrouch > /dev/null; then
    bartycrouch update -x
    bartycrouch lint -x
else
    echo "warning: BartyCrouch not installed, download it from https://github.com/Flinesoft/BartyCrouch"
fi

The update subcommand with the normalize option harmonizeWithSource set to true ensures that all keys I add to the sourceLocale "en" will automatically be added to any other languages my app supports. Additionally, I prefer to sort all keys alphabetically (sortByKeys) to keep any keys with the same prefix like Onboarding.LoginScreen. grouped together.

The lint subcommand with emptyValues set to true ensures that I get warnings within Xcode for any empty localization values. The duplicateKeys option ensures that I also get warned if I accidentally would add a key to the "en" localization manually to prevent ambiguity.

So BartyCrouch seems to continue helping with localization, even with SwiftUI. But it requires a manual step to add a key to the source language at the moment and it can't check for the existence of the key in the localization files.

To explore how I can fix this, I wrote a shadow type named SafeLocalizedStringKey that conforms to the same protocols and passes the localized Strings along to LocalizedStringKey. Additionally, I overloaded all SwiftUI view initializers that were using LocalizedStringKey with a safe: variant that has a validation for the existence of keys that would only run during development, but would safely fallback to the key in production. I achieved that by using this validation method:

func validateAvailabilityInSupportedLocales(stringsKey: String) {
    #if DEBUG
    let missingLocales: [String] = Bundle.main.localizations.filter { locale in
        let localeBundle = Bundle(path: Bundle.main.path(forResource: locale, ofType: "lproj")!)!
        let localizedValue = NSLocalizedString(stringsKey, bundle: localeBundle, comment: "")
        return localizedValue == stringsKey || localizedValue.isEmpty
    }

    guard missingLocales.isEmpty else {
        assertionFailure("Missing locales \(missingLocales) for localized string key '\(stringsKey)'.")
        return
    }
    #endif
}

This code first filters the locales that don't have an entry for the key (in which case the value is equal to the key) and reports them as an assertionFailure, which ensures that this code doesn't crash the app in production even if the DEBUG was set for production builds accidentally.

You can find the full implementation of the SafeLocalizedStringKey type in this GitHub gist, including the safe: overload extensions for 17 different SwiftUI views. If you copy that file into your SwiftUI project, you should be able to replace any calls like Text("E-Mail") with the safe alternative Text(safe: "E-Mail"). This will run the additional validation and prevent you from forgetting to add the key to your localization files as it will crash the app during development with a clear warning.

So far so good, I'm happy enough with this solution for now. Improvements were made on all of the localization flaws.

Of course it would be even better to have a solution that automatically takes care of adding the keys to the localization files like the "Pro localization workflow" in my previous article, but that's out of scope of this exploration as I want to focus on getting my app closer to release first.

The only other improvement I actually did was to write a custom lint check using AnyLint to make sure I never forget to use the safe: APIs over the default ones. The check even autocorrects the non-safe API usage to safe APIs automatically and could be run as a pre-commit hook. I've uploaded it as a GitHub gist in case you want to use it.

That's it from me today, I hope you found something useful in this article. What do you think of my approach taken here? Do you have other ideas that can improve localization with SwiftUI? Let me know by leaving a comment below.

Thank you for your time!

DEV Community: Cihat Gündüz

Laser Focus priority strategy

Laser Focus categories

Vital

Essential

Completing

Optional

Retracting

Laser Focus matrix

Laser Focus breakdown

Summary

Git Merge vs Rebase

What is a merge?

What is a rebase?

What are the main differences between merge and rebase?

In which situations should we use a merge?

In which situations should we use a rebase?

Why not use merge to merge changes from the base branch into a work branch?

Example Git History when using merge:

Example Git History when using rebase:

Are there any downsides / pitfalls with rebase?

Tips to reduce merge conflicts when using rebase:

Primer on Regexes

What are Regular Expressions even?

What can I do with the "Regex DSL"?

1. matches

2. captures

3. replace

What does the "Regex DSL" look like?

1. Character/Group Modifiers (e.g. *, +, {,}, ?)

2. Custom Sets (created with [ and ])

3. Predefined Sets (\s, \S, \d, \D, \w, \W)

4. Groups (e.g. ( and ), (?<name> and ))

5. Match Modifiers (\A, \z, ^, $, Lookarounds)

Common Quirks and validating new Regexes

How can I use Regexes in my projects today?

Safer Localization in SwiftUI

What is a `merge`?

What is a `rebase`?

What are the main differences between `merge` and `rebase`?

In which situations should we use a `merge`?

In which situations should we use a `rebase`?

Why not use `merge` to merge changes from the base branch into a work branch?

Example Git History when using `merge`:

Example Git History when using `rebase`:

Are there any downsides / pitfalls with `rebase`?

Tips to reduce merge conflicts when using `rebase`:

1. `matches`

2. `captures`

3. `replace`

1. Character/Group Modifiers (e.g. `*`, `+`, `{,}`, `?`)

2. Custom Sets (created with `[` and `]`)

3. Predefined Sets (`\s`, `\S`, `\d`, `\D`, `\w`, `\W`)

4. Groups (e.g. `(` and `)`, `(?<name>` and `)`)

5. Match Modifiers (`\A`, `\z`, `^`, `$`, Lookarounds)