Daniele Margutti

HTTP Client for Swift

2025-06-18T00:00:00+00:00

Oh dear, just what I needed… another delightful request for a refactor!

Oh no! Yet another refactor request!

2025-02-14T00:00:00+00:00

Oh dear, just what I needed… another delightful request for a refactor!

You can bet this is the first—and probably the second—thought that crosses the mind of any manager or engineering lead when some dev pops up with a shiny refactor idea during any brainstorming or planning session. It’s like, “Oh great, here we go again!”

That’s because there are few—like, really few—valid reasons for something to deserve a refactor.

But hey, that’s a topic for another post!

Anyway, getting management to understand that you need a significant amount of time for a meaningful code refactor is quite hard.

It’s basically a negotiation, so having your homework done is key.

Despite what you think, for the company, initiating a refactor is seen as a risky move that takes time away from - literally - any other activity.

And let’s be honest, it usually involves something that actually works—albeit in a messy, ugly, and barely maintainable way. But hey, after a lot of patches, it still delivers the goods!
It’s like trying to convince someone to fix a leaky sink when the water is still flowing.

You know it’ll be better in the long run, but getting buy-in is no walk in the park!

Who do you talk to?

Your primary goal is to make your needs align with the person you’re talking to.

Speaking the same language is crucial: for instance, someone who isn’t very technical won’t care much about the benefits of clean code, but they will likely be interested in how performance will change as a result of this activity.

Use concrete examples to explain how the current codebase is holding the team back, how refactoring can improve the status quo, and when applicable translate the benefits to hours or money.

The yourney so far

One of the big questions non technical execs have is “why did the codebase end up in this state in the first place”. Depending on who your audience is it may be important to have this information in your presentation.

Knowing what led to the current situation (when possible) shows a deep understanding of the problem and boosts your reliability in activities that can help set things straight.

Something like that adds context and justification that a non technical execs will understand.

The Evidencies

Refactoring should be treated just like any other project. Don’t just stop at chit-chat: if you can, strengthen your case with some solid data. Metrics, benchmarks, user feedback, and even downtimes are just a few nuggets you can pull out to showcase the potential benefits of a refactor.

The more evidence of possible improvements you have, the better you can paint the picture of why refactor is crucial (ROI / Return Of Investment).

It’s all about making your argument as bulletproof as possible!
After all, numbers don’t lie, and they can help turn skeptics into supporters.

Be sure to show how the benefits of the change.

How will reduce security risk leading to a possible litigation
How many hours will be saved on future development

The Plan

Make sure you have a rough plan. Of course, you won’t stick to it perfectly, but that’s okay because:

It’ll help your conversation partner grasp the effort involved; especially for those who aren’t technical, it’ll make it easier to understand the scope of the work.
It’ll allow you to really get a handle on the problem, forcing you to break it down into smaller tasks, which makes it easier to delegate to the team.

When you can show the problem and make a detailed plan to solve it, it’s hard to get no as an answer.

Anyway, the best way to avoid huge refactoring is to make refactoring part of your daily/sprint routine.

One step at time

A big refactor isn’t something you can whip up in a day, and management might need some time to wrap their heads around it.
Stay patient, keep pushing, and make sure to keep the communication flowing!

Fixing the Xcode 16 LLDB error "Couldn’t realize type of self”

2024-12-06T00:00:00+00:00

Programming on iOS has never just been about chasing after Apple’s new APIs; often—indeed, more than necessary—it involves implementing more or less creative workarounds to overcome issues that arise specifically with the toolchains, Xcode being the primary one.

Since the introduction of Swift—ten years ago now—the quality of debugging apps with complex architectures has always been a battleground. From time to time, we find ourselves dealing with a debugger that just won’t cooperate.

The latest issue is with Xcode 16.0; basically, the error pops up when you try to use po :

error: type for self cannot be reconstructed: type for typename "$s15IndomioControls17AdsCollectionViewCD" was not found (cached)
error: Couldn't realize Swift AST type of self. Hint: using `v` to directly inspect variables and fields may still work.

The error appears only when you set a breakpoint in a Swift files.
There is no issues while debugging Obj-C file (I miss you bro).
Moreover it only affects the debugging part, but it doesn’t impact the compilation or the runtime execution of the code.

You’re really just left unable to debug the code—nothing too serious, right? I mean, who needs a debugger anyway? You can always just print stuff out like it’s the good old days!

I know you’re just itching for the solution; so if you’re about to lose your mind and really can’t be bothered to learn anything new, go ahead and skip straight to the last chapter of this article.

p, po, v… what the heck?

In our case, the problem occurs for all the modules (frameworks imported via SPM) linked to the main project. It was impossible to debug any variable, even when trying with the commands p or v (and, to top it off, the LLDB server crashed more than once).

The funny thing is that in the Variable View of Xcode, the variables were almost always visible.
Hint: you can ge the same output of the Variable View by using the command frame variable <name_variable>.

But, what’s po and why isn’t working?
Before that we need to briefly talk about LLDB.

How LLDB is able to format variables

LLDB isn’t just a debugger: it’s also a compiler—yep!
With copies of both the Swift and Clang compilers, it can evaluate complex expressions (with p/po being just aliases) and alter the program’s state using expr.

But how does a debugger format a variable? Let’s consider the following statement:

let data = "Hello World"

If we hit a breakpoint in LLDB and try to print the content of a variable in a raw way, we get, as expected, a bunch of bytes:

(lldb) frame variable -L data // obtain the memory address
   0x0000000100008000

(lldb) mem read 0x0000000100008000 // print the address content
   0x100008000: 48 65 6c 6c 6f 20 57 6f 72 6c 64 00 00 00 00 eb  Hello World.....
   0x100008010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................

Not very helpful, right?
To provide a pretty printed format of the data, LLDB needs to know the types of these data (Int, String, Dictionary, MyClass etc.).

Since Xcode 14.x, this information comes from 2 different side, which explains why different commands may work or not:

DEBUGGER SIDE
Here the p and frame commands lives.
Type information is obtained from Debug Info (the .o and .dSYM) and by using Swift Reflection.
COMPILER SIDE
Hhere the po and expr commands lives.
Type information is obtained from Modules: .swiftmodule, .modulemap, .h, and bridging-header.h.?

Modules are how the compilers organizes type declarations.
But we’ll get back to this in a bit; have you ever heard of swift-healthcheck?

swift-healthcheck to the rescue!

This command was added a couple of years ago and is the first thing to keep in mind when analyzing a problem related to modules.

If we execute swift-healthcheck after a problem with LLDB occour we can get access to a log the inner process of the Swift expression evaluator.

Let’s get back to our problem and try executing the command:

(lldb) po self.adId
   error: type for self cannot be reconstructed: type for typename 
   "$s11IndomioCore7HTTPOpsO8AdDetailCD" was not found
   error: Couldn't realize Swift AST type of self. Hint: using `v` to directly inspect 
   variables and fields may still work.

(lldb) swift-healthcheck
   Health check written to /var/folders/fp/h_f5_67x16bbsfp5g4f76jc40000gn/T/lldb
   /72168/lldb-healthcheck-512ff2.log

When we open the file mentioned, we find a bunch of information that can help us out.

==== LLDB swift-healthcheck log. ===
...
SwiftASTContextForExpressions(module: "IndomioCore", cu: "HTTPOps+Ad.swift")::LoadOneModule() -- Missing Swift module or Clang module found for "IndomioCommons", "imported" via SwiftDWARFImporterDelegate. Hint: Register Swift modules with the linker using -add_ast_path.

As we said, IndomioCore is an internal framework and the error is telling us that for some reason, it failed to import the related module.
This missing module is a problem because LLDB can’t understand the data type related to self, and as a result, it can’t format it.

Where Modules come from and who register them?

Each module contains the interfaces for its own APIs.
Generally speaking:

System Frameworks
Modules are integrated within the .sdk file (e.g., MacOSX.sdk). LLDB will find a matching SDK to read them from as it’s attacching to your program on a debug session.

External Frameworks
The .dSYM package generated by the build system usually contains all the associated modules (.swiftmodule, bridging-header.h, .swiftinterface) related to the frameworks compiled by the target itself.

Dsymutil can package a debug info archive called a .dSYM bundle for every dynamic library, framework or dylib, and the executable itself.
Each of these .dSYM bundle can contain binary Swift modules.

In order for a Swift module to be picked up by dsymutil, it needs to be registered with the linker. This registration occurs automatically for dynamic libraries and executables, but not for static archives. However, in many cases, Xcode handles this for you (not for custom build systems or custom build rules).

We didn’t discover much about why Xcode sometimes fails to map these files; we suspect it might somehow relate to how we build the project through Tuist.io, but that’s just a guess for now.

The Solution

Since the issue is that Xcode (or the linker) can’t map the modules with the data types of the program’s source files (and frameworks), the only solution for now is the one proposed by swift-healthcheck.

You can explicitly specify these modules for the Debug configuration using the -add-ast-path command passed to XLinker.

(In brief, Xlinker is a command-line tool that allows developers to pass specific linker options directly when compiling applications by using -Xlinker followed by the desired option for fine control over linking.)

We have a series of internal frameworks in our architecture depending on the service layer. To get this working, we need to repeat the process individually for each framewor by setting the Other Linker Flags (OTHER_LDFLAGS) of our main app target.

    "-Xlinker",
    "-add_ast_path",
    "-Xlinker",
    "'$(TARGET_BUILD_DIR)/\(frameworkName).framework/Modules/\(frameworkName).swiftmodule/$(NATIVE_ARCH_ACTUAL)-$(LLVM_TARGET_TRIPLE_VENDOR)-$(SHALLOW_BUNDLE_TRIPLE).swiftmodule'"

where frameworkName is the name of the framework.

Since we’re using tuist.io for creating project this looks like this:

func debugOtherLDFlags(forFrameworks frameworks: [String]?) -> SettingValue {
    var otherLdFlags = ["-ObjC"] // default flag
    frameworks?.forEach { otherLdFlags += astPathForFramework($0) }
    return SettingValue.array(otherLdFlags)
}

func astPathForFramework(_ name: String) -> [String] {
    [
        "-Xlinker",
        "-add_ast_path",
        "-Xlinker",
        "'$(TARGET_BUILD_DIR)/\(name).framework/Modules/\(name).swiftmodule/$(NATIVE_ARCH_ACTUAL)-$(LLVM_TARGET_TRIPLE_VENDOR)-$(SHALLOW_BUNDLE_TRIPLE).swiftmodule'"
    ]
}

And boom, magically your debugger is back to working!

This article wouldn’t have been possible without the help of the Immobiliare.it team (especially @stedurso) and numerous online articles that guided us in finding the right solution.
As always, the best comes from teamwork.

The engineer you’d want to be

2024-02-28T00:00:00+00:00

Writing code is just one aspect that will make you a good engineer.
In a future where AI will be an integral part of every workflow, standing out in an increasingly crowded field will be important.

Today, while scrolling through my newsletters, I spotted this news:

It turns out that Odysseus landed on the Moon without any altimetry data […] The moon lander’s range finders were discovered to be inoperable a couple of hours before it was due to attempt to land on the Moon, so the company rewrote its software to take advantage of three telescopes on a NASA payload for altimetry purposes. (TLDR)

Odysseus is the lander (developed by Intuitive Machines) that reopened the discussion about the Moon as a stable outpost after more than 50 years since the last Apollo mission.
Last Friday, the lander landed on the lunar surface, albeit not without issues.
Just a few hours after landing, IM discovered that the lander had inactive range finders (apparently missing a pencil-sized pin and a connector that allowed turning the laser on and off)

Reading this captivating story, I found myself reflecting on the countless occasions when, addressing challenges with my team, I’ve jokingly remarked, “Well, it’s not like we’re sending rockets to the moon, right?”.

Indeed, it’s true.
Most of the time, “good enough” suffices.

Many developers often content themselves with slapping on the first patch they find, convinced that the surrounding environment (high-performance hardware, user use cases, etc.) will compensate for deficiencies.

Many of them end up labeling bigger problems with a nice “refactor” tag.

It needs rewriting.
Too hard to understand, poorly written, incomprehensible, no documentation.
It’s better to start over.

I know because I did it myself for a long time.
It’s easier, it’s just more fun. Let’s rewrite everything!

The world we’re heading towards

However, the world we’re heading towards, on one hand, is creating a large audience of developers capable of producing something “good enough” even with the help of AI, and on the other hand, it demands from developers skills that go beyond the latest shiny framework of the moment.

Companies have never sought ninja developers, just as they won’t seek proficient prompters to indoctrinate AI. What they’re looking for instead are professionals they can rely on.

If there’s a problem, no manager wants to hear: “Let’s rewrite everything from scratch in the newest framework x instead of y, so we won’t have that problem anymore” .
Why? Most of the time solves a known problem only to add new ones that are still unknown.

What is expected instead is the responsiveness to request the appropriate time to deeply analyze and propose solutions (and perhaps those solutions will end up being a rewrite, but they’ll be so while explicitly stating real reasons, not assumptions).

Being able to read and analyze others’ code is crucial, even more so than being able to write it.
Unless you are the only programmer on Earth.

Can you picture if, when faced with a complex problem like the one with Odysseyum, Intuitive Machine’s engineers had just thrown up their hands and said:
“Ah well, let’s start from scratch the next time”?

Instead:

As a result, the company scrambled to rewrite its software to take advantage of three telescopes on a NASA payload, the Navigation Doppler Lidar for Precise Velocity and Range Sensing, for altimetry purposes.

Being adaptable, responsive, and analytical makes a tech person more than just a code writer.
Digging deep into topics and issues is what will really make you stand out in a growing crowd.

Don't hire for passion

2024-01-28T00:00:00+00:00

Let me to be honest, there is a big lie in the world:

Do what you love and you’ll never work a day in your life.

If you’re reading this post and you know me, you’re probably wondering if I’ve lost my mind or something. I joined the world of computer science driven by a strong passion.

Yet, many years of technical interviews with dozens and dozens of people of all seniorities have left me with a bitter realization.
You really should try to avoid making assumptions based on how passionate the person in front of you appears to be.
You don’t want to hire passionate people.
You want to hire professional people.

Yeah, I get it. Passionate folks often have extra drive, maybe even find the best or most efficient solution (unless they get stuck in their own loop).
But let’s face it, relying on their reliability can be iffy.

But why? Passion is, by definition, illogical.
It often leads people to act without thinking - we call them crimes of passion for a right reason.
People lead by passion are generally poorly accountable in most of the situations.

Mostly, though, the distinction here is that the professional will do the parts of the job they dislike just as they will the parts they like - the professional knows it’s a job, not a life choice or an identity. You can’t say the same for passionate ones.

Most of the time, if these individuals can’t manage themselves, they need to be fed with new challenges. Sometimes these tasks end up being created ad hoc without a real need. It’s equally true that once any resource is depleted, they’ll be the first to leave to plunder another team.

So, unless you’re developing the next rocket to Mars or you’re absolutely sure that person can feed their ego outside the team, my advice is to move on.

If you are building a team or you’re a passionate developer take a look at the link below and read it carefully.

Beyond specialization

2023-08-10T00:00:00+00:00

I dove into programming at a young age, driven by boundless curiosity.
It was a world where anything was possible, and that very curiosity became my lifelong passion, eventually evolving into my career.

The fact that it also happened to be a pretty cool job in these years was just a lucky coincidence.
If I’d been into poetry, I might be under a bridge right now, scribbling away!

Anyway, for a long time, I lived in a world that strongly encouraged specialization as a career path. The fact that many schools, especially at higher levels, emphasize strong specialization represents the epitome of this way of thinking.

The term ninja developer, which was quite popular a few years ago (now mostly used with a negative connotation), perfectly encapsulates this perspective.To summarize this thought, hyper-specialization was once seen as the only way to pick the high-hanging fruit in fields where the low branches are bare.Moreover specialization feels like a more predictable and measurable path for a tech career.

Unfortunately, as the world of software has become more complex and diverse in terms of skills and professions, being highly specialized doesn’t always pay off.

While it’s true that a highly specialized team can push the limits in each field, in most companies, this isn’t strictly necessary.
What truly matters is how diverse professions can seamlessly interact, mutually influence, and comprehend one another effectively.

Recently at my company we’ve been recently trying out small project teams (a.k.a. pods) with measurable business goals and time constraints.These teams often have a mix of professionals like designers, frontend/backend developers, and product owners.

After a few tries, some more successful than others, we came to appreciate how essential it was to find the perfect mix of personalities for our team.Typically, teams consisting of individuals with hybrid skill sets were more adept at cultivating empathy and understanding among their members.

Why we need hybrid people?

The world needs more hybrid people because the world is getting more complex.While specialists are important because they help us push the limits in each field, we also need people who can see the big picture and guide the team efforts.

Having a wide base of skills with one or two specialties gives you more tools in your toolbox — more ways and points of views to solve problems effectively.

You can think of these individuals as the alloys of various materials:

These constituent materials have notably dissimilar chemical or physical properties and are merged to create a material with properties unlike the individual elements.— wikipedia

Embracing hybrid skills enables you to excel beyond the sum of your individual capabilities and hones your empathy in comprehending and embracing diverse viewpoints.

Returning to our experiment, I observed how [sometimes] highly specialized team members with lower empathy skills can be sources of friction within the whole team. This resulted in a negative overall perception of the work and, consequently, less favorable outcomes (even though, theoretically, we had higher technical skills).

To sum it up

In the end, my suggestion is to explore areas as distant as possible from your own expertise, while sharpening your empathy and understanding.

You might not always need to perform an Apollo 13-style astronaut rescue, but you’ll frequently encounter situations that feel light-years away from your usual work. Mastering these situations with finesse will make you a more well-rounded and valuable professional in countless settings.

If you had a blast reading this, why not hop on board our newsletter? You’ll get all the latest posts delivered right to your inbox. No spam. Seriously, we pinky promise!

Your thoughts

Do you think hybridizing could supercharge your career, or is specialization your secret sauce for job satisfaction? Share your insights; drop a comment below!

Literatures

Technical literature defines these types of individuals
An interesting read on the topic “Range: Why Generalists Triumph in a Specialized”

Task & Threads in Swift Concurrency

2023-08-05T00:00:00+00:00

To understand the difference between tasks and threads, we need to take a look at what threads are and how they are used in a modern general-purpose computer.

Since this is not a post about CPU architectures I’ll try to simplify some concepts.

At the very low level every processor has a thing called registers.We can refer to registers as a type of computer memory built directly into the processor that is used to store and manipulate data during the execution of a program instructions.

CPU Registers

A register is just like container for a variable; modern processors uses 64-bit registers, which means a single unit can store 64 bits of data (8 bytes).

When a CPU executes a program it loads data from RAM into register, does operations and store them back to the memory.

A modern CPU has multiple cores, each with one set of registers including a program counter. Some CPUs have two sets of registers per core for faster thread switching (we call it hyper-threading).For sake of simplicity a core is an entire CPU that just happens to be attached to the first one for faster communication.There are different types of registers: unfortunately while we’re allowed to have a large amount of local variables, there are a limited amount of registers into a CPU.To handle this issue there is a region of the memory (RAM) used to store local variables that aren’t currently in registers.

This region is called Stack: each time you call a function its variables get added to the top of the list; once a function body is finished their variables are taken off the top (the concept of a stack).

Threads

Threads are a sequence of execution of code which can be executed independently of one another. You can consider it as the smallest unit of operations that can be executing by an operating system.

At the very low level a thread is represented as a snapshot of the CPU, specifically the state of all the registers, the content of the stack and few other stuff used by the kernel to keep track of the thread.

Modern CPUs runs multi-tasking OSs which allows to switch which thread is running at frequent intervals allowing the concurrency happens.Each thread is executed for a limited amount of time, then a context switch happens and so on (in a multi-core environment, concurrency can be achieved via parallelism in which multiple tasks are executed simultaneously if they are independent each others).

Context switching can be:

Voluntary: the thread has completed its work and reports it to the kernel” (cooperative multitasking).
Non-Voluntary: the scheduled time for the thread has ended for now, and execution is temporarily suspended by the kernel (preemptively multitasking).

Preemptive multitasking allows for better resource management and prevents poorly-behaved programs from taking full control of the system (more on differences).

The hidden cost of threads

The context switching doesn’t come for free; in fact, it has a cost.When the OSs suspend a thread it must save all the registers into the RAM, then load the state of the incoming thread previously saved on RAM.

The load/unload operations of threads take time and memory. Moreover, the kernel needs to keep track of these threads to resume or suspend them, which means additional memory usage.

NOTE: Keep in mind that significant progress has been made in processor and operating system architectures. Today, a thread can share various state information with other threads, reducing overhead. Most processors, especially multi-core processors and GPUs (graphics processing units), now incorporate hardware that makes running multiple threads particularly efficient.Nevertheless, it’s important to consider that thread models may not be well-suited for all computer architectures, and this remains an optimization problem.

Swift’s Task

The new Swift Concurrency Model uses an hybrid approach: it has a lightweight thread-like object called Task (in other languages they call it coroutines or fibers or, simply, program threads - vs kernel threads).OS’s Kernel know nothing about these objects. It’s fully managed by the internal Swift’s concurrency library. You can consider it a new abstraction layer over the OS.

The Concurrency Library does its own cooperative multitasking to decide which tasks needs to be mapped to real threads. Every time we’re using the await statement, we’re telling to the library it’s someone els’s turn, giving up your actual thread.

This model is called M:N Threading Model or Hybrid Threading (there are 3 different types of threading models).

This a model which maps M user threads onto N kernel threads.This enables a large number (M) of user threads to be created, due to their light weight, which still allowing (N-way) parallelism.Many other languages uses this model to create lightweight threads.

The advantage over using one thread for each task (kernel only threading) is that you consume less resources, like memory (both virtual and physical) and kernel objects. You also get less context switches, which increases performance (in the ideal case, where you have as many running threads as you have processors, you may have almost no context switches).

The advantage over user only threading is that you can take advantage of multiple CPUs or multiple CPU cores. And if one task blocks, you can create another kernel thread to use the available CPU more efficiently.

A disadvantage over kernel only scheduling is possibly bigger latency: if all the threads in the pool are busy and you add new short task, you may wait a long time before it starts executing.

In the best case scenario that what previously would have required many many and expensive real threads, each running for a short period of time, now requires only a tiny number of real threads.

Moreover they all run for as long as the kernel will let them, minimizing both memory overhead and therefore the switching cost.

Threads Explosion

Since this topic is somewhat off-topic, I will briefly mention the concept of thread explosion, leaving links to two articles that delve into the issue at the end.

As we said context switch has a performance cost. When this happens a lot (you create manu more threads compared to the number of available CPU cores) the context switching grows high: this event is called threads explosion.

This lead to some issues like:

Memory overhead: each blocked thread is holding onto valuable memory and resources while waiting to run again.
Scheduling overhead - as new threads are brought up, the CPU need to perform a full thread context switch in order to switch away from the old thread to start executing the new thread. With limited cores and a lot of threads, the scheduling latencies of these threads outweigh the amount of useful work they would do, therefore, resulting in the CPU running less efficiently as well.

While Swift Concurrency is doing a pretty good job of preventing thread explosion, we cannot deny the fact that it will cause a very significant bottleneck in some cases.If you want to know more about this topic you can watch the WWDC21 Session “Behind the scenes” and read this interesting article by Senpai “Swift Concurrency vs Thread Explosion”.

Literatures

“Differences between Preemptive and Cooperative Multitasking” by JavaPoint
An interesting article about threading models “Threading Models”
As fair I know it should be used by Go (with goroutines), Erlang (with processes) but also by C++, Java and Python. In fact Go and Erlang go further with another layer called O:M:N thread model.

The effect of indirect actions on team dynamics

2023-04-10T00:00:00+00:00

When I started this role about 4+ years ago, I never thought about how indirect actions could shape the people around me even more than any direct action or speech on the stage.
This is true both in the short and long term.

Some time ago, during a break, we discussed this pattern along with some colleagues. It’s impressive to see how people slowly start to imitate their managers in their everyday work life, both in positive and negative aspects.

Looking at everyday life, it’s easy to recognize how the mood of those around us very influences us. Usually, it’s not even something we do consciously; most of the time we unconsciously pick up on a different tone of voice, observe the body language of people nearby, and our brain does the rest.

Nothing strange; in fact, our brain is hard-wired for this stuff.We are constantly on the lookout for threats in our environment that could lead to bad news. Our brain assembles signals from gestures, voice tone, facial expression, words, and so on to infer behavior or make (sometimes wrong) assumptions.

Moreover, humans tend to mirror each other.Mirroring is a nonverbal technique where a person copies another person’s body language, attitude, or vocal qualities.From an evolutionary perspective, being in sync with members of your group is vital to survival; it signals that we are connected to a person in some way. The whole point of mirroring is that it’s a way to understand better and connect with others.Being able to mirror someone is the same as listening to someone.

How does this affect your role?

Spreading fever is not a good idea, even if there are reasons to feel sick.

Mirroring in teams is a sign of trust, but you must take it responsibly.How often have you left a bad meeting only to have those strange vibes picked up by other people?

I consider myself a very empathetic person.It’s easy for me to pick up on the general mood of a person or group in the room. For the same reason, it has always been easy for me to influence (and be influenced by) the “temperature” of people.

However, in any leadership role (and generally speaking, every senior role) part of the job is to learn when and how to intentionally change the vibes in the room.Sometimes it’s not spreading flu, but just a rash.Some other times instead, you need to take action to avoid worse situations.

It’s not always easy, that’s for sure.You will end up making many more mistakes than you would like.But it’s an exercise that you carry with you throughout your entire life.

I would love to take a look at some tricks you can apply to reset the temperature of a group when a flu is about to spread all over the members.

Reset the temperature

Model the environment using your tone, body language, and wise word choice.

If you’re noticing a major shift in someone’s demeanor, instead of guessing what’s going on for them, it is better to ask an open question about what they need or how they’re feeling.

Be intentional about the tone that you’re using since your body language always reflects your real mood. You’re responsible for communicating that you want to hear what they have to say, and that you’re here to support them.

Soft eye contact is better than keeping constant eye contact (which is, frankly, a little creepy). You can break eye contact every few seconds naturally, then connect again, and this still feels attentive and affirming to the other person.

You smiled a bit, told a little joke that made them chuckle, and nodded at the pace that they spoke to indicate you were listening, and their mood started to change.Sometimes people may feel overwhelmed, stressed, or distracted. In these situations, the best way you can do is to take a break.It’s like when you feel stuck with a coding issue.That’s the same, take a breath… and a break.Offer a pause in the conversation and a plan to return to it later.Try to intentionally avoid putting someone else on the spot or making them feel attacked:

“I really want to support you on this.How would you feel about us taking a break now to spend some more time thinking it through?”

What I learned

If you aim to be in a leadership role, you’re a senior engineer or you’re in charge of a team, you should always remember how strongly indirect actions can influence all the members of your group.Moreover, it’s your responsibility to avoid acting like a flu spreader.You need to acknowledge tense or awkward situations, or you’re going to risk developing a forever-antagonistic relationship with them.Also not supported assumptions can lead you to the wrong path: talk to the people.

Not everything has to be perfect the first time

2022-08-04T00:00:00+00:00

It’s strange, but it often happens to many senior people: the more you move towards your career, the more it’s hard to love imperfection.

Each new project starts with constraints: some of them are related to time-to-market bounds, some others instead came from the necessity to optimize and delay the necessary resources (mostly development time) while evaluating user feedback.

Constraints mean that we have to pick things that will get as much attention as we would ideally like. The results are removed features, less-than-ideal technical approaches, troubles for some teams, and so on.

Engineers and the idea of perfection

It’s hard not to want everything to be perfect, and it’s harder to convince people about what’s behind these constraints.

This is where I’ve often encountered great engineers, product managers, and designers getting lost.

But at this point, I must confess: I damn hate the MVP term. MVP is the acronym for “Minimum Viable Product”. Even with all the best intentions, it’s just a game of diminishing returns: “minimum” stands for “the least effort“; “viable” is another low bar meaning something isn’t often desirable.

Definitely, it’s far from being something someone can be excited or nevertheless proud of.

Communication is essential: words matter.
(Especially when you’re talking to a tech team)
MVP is often considered a slap in any tech people’s face; less than ideal, the symbol of “imperfection”.

Most engineers refuse the idea of imperfection.
The first message you should pass is to get the team comfortable with the uncertainty of software development.

Time delays, requirements, and goals changes; depending on the area, everyone can feel the volatility of the development process of a new feature on their skin.

Not everything has to be perfect the first time

Explaining the reasons behind choices is fundamental to align the product and tech team better. It’s not about high-fidelity mockups; it’s more about sharing measurable goals behind the idea.

Knowing what truly has to be perfect can help focus limited resources on the right spot.

Then: not everything has to be perfect the first time.

Communicating your goals with a detailed long-term roadmap is a typical error.
The far future is unknown, at best.
It will constantly change as you move forward: reduce the detail in your plans as they get farther ahead avoid overthinking.

As I said at the beginning of this post, it’s hard to love imperfection.
Most of the time, the response to “we can fix it later” is something in between melancholy and sad: “we probably won’t”.

Teams are asked to compromise daily; promises of “we’ll fix it later” sound really hollow if you, as manager, don’t create a structured workflow with enough space to fix and optimize things.

Conclusion

Developing any digital product is stressful for both product and tech teams. Both will experience the pain of removing features, changing priorities, and reducing/expanding time daily.

As a manager is critical to focus on better goal settings & communication: what’s important, what’s not, what’s the reason behind a choice.

As an engineer is essential to feel comfortable with the ever-present uncertainty of making digital products. Resources are limited: reduce the scope, be crafty, focused, and precise.
You will never get perfection in a constantly changing world, and no one needs them.

Thoughts on moving to a leadership role

2022-06-15T00:00:00+00:00

Moving to a leadership role does not mean you will need to check every line of each PR, tearing your hair and hoping it will be not that bad day.

When I started the role of Technical Lead (feel free to replace it with any other variation of the role) I had a strong craving to control everything around me. This is not anything strange for tech people new to this kind of role.

Therefore it’s easy to feel overwhelmed, sad, or lost at times. This already happens in the early stages, when your team is small and the concurrent tasks are still manageable.
An example of this behavior is the attempt to perform every code review.
Probably you’re concerned that something will break if you don’t pay the necessary focus.
You won’t say anything new but, listen to me, it isn’t feasible and it does not scale.

But what you can do instead?
Some people hates code reviews but they’re an awesome opportunity to explore how someone solved a problem in their unique way and to have discussions on the programming craft.

Before anything else…
Before any automated tools, before linters and formatters you need to focus on two fundamentals activities:

Teach your team to review effectively Emphasize the scope of a review the kindness, clarity and throughness. You can’t write and review all the code for your team, neither you can hire for people for this job. Put your team in position to handle them effectively.
Establish Paradigms Setting a few paradigms and rules during product development will save your life. Once you’ve set clear boundaries, reviews become laser-focused. Reviewers can focus on the specific features and they don’t get distracted by accessory elements. A shared structure is one of the best things to invest in; others can leverage and build on top of it. Define how different parts must communicate, the overall architecture, and general approach to UI development leaving the opportunity to evolve and change it over time (gradually).

Once you have consolidated these changes you can build at the top of it:

Document processes Team members should be aware of the scope and structure of each PR. Using PR templates allows people to correctly explain what have they done and offer a clear overview to any reviewer.
Integrate Automated Tools Linters, formatters & automated tests release people from the burdens of the boring parts of a review (yeah, I know, some people are human linters but, okay). Strengthen your release pipelines with tests, monitoring, and rollback. This will help to prevent, detect and mitigate defects.

Healthy approach to code reviews

2022-04-22T00:00:00+00:00

Code reviews are weird monsters. With no doubts they improve the overall quality of the code and help programmers build relationships and work together more effectively.

However asking for a code review puts many people on edge because it is just like laying your creative soul bare. By generally speaking most of the devs lives CRs as a “personal intrusion”.

Your team is only good as your weakest reviewer

Here are some tips I’m collecting about it in these years.

Who?

Code Review is a team activity. A good mixture of senior and junior members aim to create the right environment for learning: senior members can battle test their code related to APIs clarity, junior devs have a chance to learn new things.

Depending your team size and structure each review may require one or more engineering approval to be merged. From my experience if your team is pretty small (less than 5 people) you can stick with 2 reviewers to keep a good balance on sharing knowledge.

If you are growing over 8+ (without moving to cross-functional teams) you should change your approach: your CR should require at least one engineer and you should start moving the team to a more static organization where part of the program are assigned to an ownership which is also responsible for manteniance and evolution of that code (more specialized skills, less shared knowledge with a modular architecture which follow a shared vision – we’ll look at that in one of the upcoming posts).

Depending of the affected part you may decide to assign it to more people; I’ve seen it vary, for core layers you may considering sharing the knowledge across the entire team.

Help me, help you

We don’t have hard requirements for adding descriptions to pull requests but recently I found it very useful and instructive to use Templates. It help you to create a good habit both for the author and any reviewer.

First of all the author is allowed to take a deep breath and focus on what he did, describing the idea, the implementation and force himself to take an overview look to the PR.

That said, anyone who is reviewing code will need to figure out what is changing and why it’s changing.

In general, we think it’s good to consider what people may or may not know about your PR, and aim to give them context so that they can help you.

Small PRs is not a matter of LoC

I strive to build things in small units; when planning a new milestone my approach is the old divide et impera. I want to break our code down as much as possible and submit small, digestible PRs. By doing this, the team can review quicker and move faster.

However, when you think about a small PR you often refer in terms of lines of code (LoC). Instead you should think in terms of conceptual changes.

For example, a variable name refactor maybe a big review because it may impacts lots of files in your code base. However it still small because it’s just a single concept (the renaming).

In my engineering we values and encourages the combination of small PRs and quick reviews.

Author POV

As author of a merge request is your responsibility to avoid waste of time & energy of your collegues.

CR must be:

Highly scoped and limited: Changes should have a narrow, well-defined and self-contained scope. If it takes more than one hour think about splitting it.
Correct: It must handle the problem and should be performant enough for its use case; main edge cases must be handled correctly and tested.
Readable: Reduce the cognitive load necessary for an user to be productive with your code (it includes BL, naming & organization of the classes, functions and variables).
Elegant: Ask yourself “would you be proud and excited to work with this code?” As maintainer of the program you must leave the codebase better than what it was before.
Huge refactoring is a separate activity If you are planning to make a refactoring which touches many parts of the app consider it moving in another CR. Unintended behavior changes can leak into the code base without anyone noticing.

Reviewer POV

Your work as reviewer is only partially related to the tech side; you should put yourself into the correct mindset when approaching a new merge request.

Be nice: Always assume the best intentions: everyone wrote questionable code before, it happened, and it will happen again. Be kind and avoid downplaying words by using easily, simply or just… It just don’t serves no purpose.
Point out the good things: Don’t forget to praise concise/readable/efficient/elegant code. If you learned something new or interesting while reviewing let it the author know.
Take the right time: Truly understand the task and the code used to achieve it; once you are confident start writing your thoughts. Consider splitting long review sessions if it takes more than one hour (attention to details tend to drop easily).
Ask & Provide Context: If you see something you don’t know about you should ask for details; always provide alternatives, we could make it betterdoes not make any sense.

What you should check in a Code Review

When you are doing a CR you should focus to the following list of activities:

Purpose

The reason a code exists is to satisfy one or more business requirements.

Does the code you received achieve all the requirements?
Does it well support edge cases?

Implementation

Think carefully about how you would have solved the same problem.

If it’s different, why is that? Does your implementation handle more edge cases?
Is it shorter/easier/cleaner/faster/safer (yet functionally equivalent)?
Do you see potential for useful/not-over-enginnering abstractions

Clarity

When possible code must require a low cognitive load to be understood. Over-engineering is a particular type of complexity where developers have made the code more generic than it needs to be, or added functionality that isn’t presently needed by the system.

As reviewer you should be especially vigilant about over-engineering to limiting future speculation.

Naming & Conventions

Naming and conventions are tools to reduce cognitive load. As team you should create, maintain and update your list of conventions; this set of rules does not strictly depend by technologies but also by the single personality of the team members.

By generally speaking you should keep in mind the following questions:

Are variables/classes/functions clear in their intentions?: You should be able to grasp the concepts and the flow in a reasonable amount of time.
Does the code follows your team code style?: Code should consistent with the rest of the project in terms of style, API conventions etc. Deviations could be accepted but must be discussed.
Are all comments into the code necessary?: Redundant and unnecessary comments clutter the code. Usually comments should explain why some code exists and rarely what is doing. If the code isn’t clear enough to explain itself, then there is room to make it simpler.
Handle TODOs: TODOs just pile up in code, and tends to become stale over time. You should be vigilant about their presence.

Tests & Docs

If your team maintain a test suits, as reviewer always ask for unit, integration, or end-to-end tests as appropriate for the change. Tests should be part of the code review unless author is handling an emergency.

Does the test cover interesting cases? Truly untestable features are rare, but untested implementations are too common.
Are tests readable? You should be able to understand what a test do.
Does this CR break backward compatibility? Think carefully existing production code and check if new code can break compatibility somewhere.
Was the external documentation updated? Outdated documentation is worse than none.

Key Takeaways

Keep in mind: code review is an asynchrnous activity don’t bother your reviewers with real-time communication unless you can’t come to an agreement or you think it’s necessary to the complexity of the changes.

Internet is full of articles about this topic; the links below are a short list of further readings where other details are discussed.

The broken window principle applied to software

2022-03-28T00:00:00+00:00

“Broken Windows” is one of the most cited articles in the history of criminology. The theory was first suggested in the early 1980s by a social scientist, George L. Kelling, in his article in the Atlantic.

It follows an experiment conducted by Standford’s psychologist Philip Zimbardo in 1969. Kelling explained the theory as follows:

“Consider a building with a few broken windows. If the windows are not repaired, the tendency is for vandals to break a few more windows. Eventually, they may even break into the building, and if it’s unoccupied, perhaps become squatters or light fires inside.

Or, in a more lightweight version:

“Consider a pavement. Some litter accumulates. Soon, more litter accumulates. Eventually, people even start leaving bags of refuse from take-out restaurants there or even break into cars.”

If you like the topic there is an entire literature on this subject; take a look at “Fixing Broken Windows”.

A 2019 study on this topic, revealed that the survey can be unreliable because people’s perception of the disorder in their neighborhoods may be intertwined with their assessments of crime as well as how they describe their own mental or physical health.

In fact, he says that policing and public health strategies shouldn’t be based on the idea that disorder causes people to break the law or participate in dangerous or unhealthy behavior.

However, that disorder, if studied in a more precise way, can provide valuable insight into what’s happening in neighborhoods and inform public policy.

An insanely detail-oriented activity

Software Design is an insanely detail-oriented activity; while a broken window does not necessarily mean stolen wheels in a nearby car, the relationship between different components in software can be much much tighter.

When your team is not on top of the details, the general perception is that things are out of control, and it’s only a matter of time before your project spins out of control and everyone stops caring about maintenance & evolution.

If you’ve been following me for some time, you will know already that I do not believe in perfectionism, especially in software design. No project is going to be perfect: in a highly mutable environment with constantly changing constraints you just can’t define a bullet points list with must-have conditions for perfection. Nick Gracilla explained this concept with a beautiful quote:

Great software architecture is like great plumbing — but for a house, that’s constantly changing

Great software architecture is adaptable; it can handle the constant change businesses place on software and is ready for future iterations and the problem definition changes.

OK, wait, wait. Let’s just back off for one second. What’s the “broken windows” theory in software design?

No one starts with bad intents

No one starts a project with the intent of making a bad job. In the beginning, principles, practices, and laws are of primary interest, even if putting them into practice might prove difficult (it also depend on team skills)

Suddenly a “window” is broken.
It may happen to high pressure to deliver or just a lack of knowledge.
People often make mistakes, even senior people. Especially senior people (“Your ego is your soul’s worst enemy” ~ Rusty Eric). But Broken windows are not just a matter of mistakes; requirements often change and you may need to make small or big changes to follow the intents at the bests.
It’s only normal.

Here there is a sliding door.
If no measures are taken technical debt starts spreading and more “windows get broken”: issues propagate in the code through imitation (“I’ve just copied that” approach), repetition (a broken assumption), or just a copy+paste.

The resulting system manifests rigidity, fragility, immobility, and lower resilience over changes. Each new change comes with a high cost, an increment of changed parts, and therefore a high risk of failure.

What Broken Window Theory Suggests

When bad behavior is not corrected immediately, it just shows people that there is no downside to breaking the rules, practices, or standards.

The absence of any negative outcome spreads the intrinsic perception of the disorder; cutting the corners becomes acceptable and quality starts decreasing.

While the problem might be complex to approach the solutions are simple:

Carry the healthy approach in your team — Senior people wanna desperately demonstrate their strengths (I’m a f*ing 10x engineer baby!), junior people how much they can do. Rarely one, two, or three days more than the estimate means something. Instead, a calm and focused approach is what can save you and your team.
Nothing comes for free — Everyone can rewrite software from the stretch; constant maintenance and evolution are far more difficult and show how you and your team are good at software design. Refactoring — like debugging — is an insightful activity to show the strengths of any developer.

Modern networking in Swift

2022-03-16T00:00:00+00:00

I’ve got a confession to make: Making networking layers has always been an exciting topic for me. Since the first days of iOS programming, in early 2007, each new project represented a fresh opportunity to refine or even break the entire approach I have used so far. My last attempt to write something on this topic is dated 2017, and I considered it a milestone after the switch to Swift language.

It’s been a long time since then; the language evolved like the system frameworks, and recently, with the introduction of the new Swift’s Concurrency Model, I decided to take a further step forward and update my approach to networking layers. This new version went through a radical redesign that allows you to write a request in just a single line of code:

let todo = try await HTTPRequest("https://jsonplaceholder.typicode.com/todos/1").fetch(Todo.self)

At this time, you may be thinking: why should I make my client instead of relying on Alamofire? You’re right. A new implementation is inevitably immature and a source of issues for a certain amount of time. Despite all, you have the opportunity to create a fine-tuned integration with your software and avoid third-party dependencies. Moreover, you can take advantage of the new Apple technologies like URLSession, Codable, Async/Await & Actors.
You can find the code on GitHub; the project is called RealHTTP.

The Client

Let’s start by defining a type for representing a client. A client (formerly HTTPClient) is a structure that comes with cookies, headers, security options, validator rules, timeout, and all other shared settings you may have in common between a group of requests. When you run a request in a client, all these properties are automatically from the client unless you customize it in a single request.

For example, when you execute an auth call and receive a JWT token, you may want to set the credentials at the client level, so any other request incorporate these data. The same happens with validators: to avoid duplicating the logic for data validation, you may want to create a new validator and let the client execute it for every request it fetches. A client is also an excellent candidate to implement retry mechanisms not available on basic URLSession implementation.

The Request

As you may imagine, a request (formerly HTTPRequest) encapsulate a single call to an endpoint.

If you have read some other articles on this topic, you may find often a common choice is to use Swift’s Generic to handle the output of a request.
Something like: struct HTTPRequest<Response>.

It allows you to strongly link the output object type to the request itself. While it’s a clever use of this fantastic construct, I found it makes the request a bit restrictive. From a practical perspective, you may need to use type erasure to handle this object outside its context. Also, conceptually, I prefer to keep the request stages (fetch ~> get raw data ~> object decode) separated and easily identifiable.

For these reasons, I chose to avoid generics and return a raw response (HTTPResponse) from a request; the object will therefore include all the functions to allow easy decode (we’ll take a look at it below).

Configure a Request

As we said, a request must allow us to easily set all the relevant attributes for a call, especially “HTTP Method” “Path,” “Query Variables,” and “Body.” What do Swift developers love more than anything else? Type-safety.

I’ve accomplished it in two ways: using configuration objects instead of literal and protocols to provide an extensible configuration along with a set of pre-made builder functions.

This is an example of request configuration:

let req = HTTPRequest {
    $0.url = URL(string: "https://.../login")!
    $0.method = .post
    $0.timeout = 15
    $0.redirectMode = redirect
    $0.maxRetries = 4
    $0.headers = HTTPHeaders([
        .init(name: .userAgent, value: myAgent),
        .init(name: "X-API-Experimental", value: "true")
    ])
    // Setup URL query params & body
    $0.addQueryParameter(name: "full", value: "1")
    $0.addQueryParameter(name: "autosignout", value: "30")
    $0.body = .json(["username": username, "pwd": pwd])
}

A typical example of type safety in action is the HTTP Method which became an enum; but also the headers which are managed using a custom HTTPHeader object, so you can write something like the following:

req.headers[.contentType] = .bmp
req.headers = .init([
  .contentType: .bmp
  "X-Custom-Header": "abc"
])

It supports both type-safe keys declaration and custom literal.

The best example of the usage of protocols is the body setup of the request. While it’s ultimately a binary stream, I decided to create a struct to hold the data content and add a set of utility methods to make the most common body structures (HTTPBody): multi-part form, JSON encoded objects, input stream, URL encoded body, etc.

The result is an:

Extensible interface: you can create a custom body container for your own data structure and set them directly. Just make it conforms to the HTTPSerializableBody protocol to allow the automatic serialization to data stream when needed.
Easy to use APIs set: you can create all of these containers directly from the static methods offered by the HTTPBody struct

Here’s an example of a multipart form:

req.body = .multipart(boundary: nil, {
  $0.add(string: "value", name: "param_1")
  $0.add(fileURL: fileURL, name: "image", mimeType: .gif)
  $0.add(string: "some other", name: "param_2")
})

Making a body with a JSON encoded object is also one line of code away:

let myObject = ...
req.body = .json(myObject)

When a request is passed to a client, the associated URLSessionTask is created automatically (in another thread) and the standard URLSession flow is therefore executed. The underlying logic still uses the URLSessionDelegate(and the other delegates of the family); you can find more in the HTTPDataLoader class.

Execute a Request

HTTPClient takes full advantage of async/await, returning the raw response from the server. Running a request is easy: just call its fetch() function. It takes an optional client argument; if not set, the default singleton HTTPClient instance is used (it means cookies, headers, and other configuration settings are related to this shared instance).

Therefore, the request is added to the destination client and, accordingly with the configuration, will be executed asynchronously. Both serialization and deserialization of the data stream are made in another Task (for the sake of simplicity, another thread). This allows us to reduce the amount of work done on the HTTPClient.

let result: HTTPResponse = try await req.fetch()

The Response

The request’s response is of type HTTPResponse; this object encapsulates all the stuff about the operation, including the raw data, the status code, optional error (received from the server or generated by a response validator), and the metrics data valid for integration debugging purposes.

The next step is to transform the raw response into a valid object (with/without a DAO). The decode() function allows you to pass the expected output object class. Usually, it’s an Codable object, but it’s also essential to enable custom object decoding, so you can also use any object that conforms to the HTTPDecodableResponse protocol. This protocol just defines a static function: static func decode(_ response: HTTPResponse) throws -> Self?.

Implementing the custom decode() function, you can do whatever you want to get the expected output. For example, I’m a firm fan of SwiftyJSON. It initially may seem a little more verbose than ‘Codable,’ but it also offers more flexibility over the edge cases, better failure handling, and a less opaque transformation process.

Since most of the time, you may want just to end up with the output decoded object, the fetch() operation also presents the optional decode parameter, so you can do fetch & decode in a single pass without passing from the raw response.

let loggedUser = try await login.fetch(User.self)

This alternate fetch() function combines both the fetch and decode in a single function; you may find it helpful when you don’t need to get the inner details of the response but just the decoded object.

Validate/Modify a Response

Using a custom client and not the shared one is to customize the logic behind the communication with your endpoint. For example, we would communicate with two different endpoints with different logic (oh man, the legacy environments…). It means both the result and errors are handled differently.

For example, the old legacy system is far away from being a REST-like system and puts errors inside the request’s body; the new one uses the shiny HTTP status code.

To handle these and more complex cases, we introduced the concept of response validators, which are very similar’s to Express’s Validators. Basically, a validator is defined by a protocol and a function that provides the request and its raw response, allowing you to decide the next step.

You can refuse the response and throw an error, accept the response or modify it, make an immediate retry or retry after executing an alternate request (this is the example for an expired JWT token that needs to be refreshed before making a further attempt with the original request).

Validators are executed in order before the response is sent to the application’s level. You can assign multiple validators to the client, and all of them can concur to the final output. This is a simplified version of the standard HTTPResponseValidator:

func validate(response: HTTPResponse, forRequest request: HTTPRequest) -> HTTPResponseValidatorResult {
if !(200..<300).contains(response.statusCode) {
// invalid response, we want to fail the request with error
        throw HTTPError.invalidResponse
    }
return .nextValidator // everything is okay, move to next validator
}

You can extend/configure it with different behavior. Moreover, the HTTPAltResponseValidator is the right validator to implement retry/after call logic. A validator can return one of the following actions defined by HTTPResponseValidatorResult:

nextValidator: just pass the handle to the next validator
failChain: stop the chain and return an error for that request
retry: retry the origin request with a strategy

Retry Strategy

One of the advantages of Alamofire is the infrastructure for adapting and retrying requests. Reimplementing it with callbacks is far from easy, but with async/await, it’s way easier. We want to implement two kinds of retry strategies: a simple retry with delay and a more complex one to execute an alternate call followed by the origin request.

Retry strategies are handled inside the URLSessionDelegate which is managed by a custom internal object called HTTPDataLoader.

The following is an over-simplified version of the logic you can find here(along with comments):

public func fetch() async throws {
    // prepare the request and execute it
    let task = try await request.urlSessionTask(inClient: client)
    let response = try await fetch(request, task: sessionTask: task)
    
    // ask to validator the action to perform on this request
    let action = client.validate(response: response, forRequest: request)
    switch action {
       case .failChain(let error):
          return HTTPResponse(error: error) // fail with error
                
       case .retry(let strategy):
          if request.isAltRequest || request.reachedMaxRetries {
            // alt request cannot be retried to avoid infinite loops
            return response
          } else {
            // perform retry strategy
            let retryResponse = try await performRetryStrategy(strategy, 
                              forRequest: request, task: sessionTask,
                              withResponse: response)
             return retryResponse
          }
       case .nextValidator:
          return response // validation okay
     }
}

If you are thinking about using auto-retries for connectivity issues, consider using waitsForConnectivity instead. If the request does fail with a network issue, it’s usually best to communicate an error to the user. With NWPathMonitor you can still monitor the connection to your server and retry automatically.

Debugging

Debugging is important; a standard way to exchange networking calls with backend teams is cURL. It doesn’t need an introduction. There is an extensionboth for HTTPRequest and HTTPResponse which generates a cURL command for the underlying URLRequest.

Ideally, you should call cURLDescription on request/response and you will get all the information automatically, including the parent’s HTTPClient settings.

Other Features

This article would have been a lot longer. We didn’t cover topics like SSL Pinning, Large File Download/Resume, Requests Mocking, and HTTP Caching. All these features are currently implemented and working on the GitHub project, so if you are interested you can look directly at sources. By the way, I’ve reused the same approaches you have seen above.

How Feature Flags can boost your mobile app

2022-01-26T00:00:00+00:00

Modern mobile development moves quickly; here in our team, we release a new version of our iOS app every two weeks.

If you are lucky enough to live the moment of a team expansion you will also see the exact moment where everything starts slowing down because you have multiple in-progress things that aren’t quite ready for production.

It’s a typical scaling problem where you need to rethink how you and your team perform everyday jobs (if you are experiencing this transition you should really take a look at “Mobile Apps at Scale” by Gergely Orosz).

Great features take time to build. How do you let the team work efficiently — free to experiment — whilst keeping the app in a releasable state?

Feature Flags is one of the strategies you can use to better handle the increase of traffic in your team repositories.

What’s a Feature Flag?

Some people call them “Feature Toggles”, some other “Feature Switch” or “Feature Controls”. All of them are names for a feature management solution that enables developers or product manager to change product’s functionality without deploying new code.

You can consider a feature flag as a decision stop-point in your code that can change the behavior of your product. You may choose to allow developers/tester/product team to adjust these values at runtime.

“(…) feature flagging is to experimentation as machine learning is to AI, you cannot have the second without the first one” JustEat Tech Blog

Common Scenarios

Feature flags are helpful for numerous scenarios typical with mobile development teams.

Avoid Long-Lasting Branches

In this environment, you can let developers merge in their code without working on long-lasting branches (every dev hates resolving boring merge conflicts every time for days or, worse, entire weeks).

Feature flags allows to keep your MRs small & focused, the main branch can be continuously updated and you can release nightly builds with no worries (*).

Reduce the risk

Bugs happen — even with the best developers and rigorous testing techniques.

Imagine this: after months of work-in-progress your team have just release a new amazing feature and you’re exicited for your users to try it out. Unfortunately, things don’t go the way you thought they would and you found an unexpected bug. Now you can either deploy an hot fix or revert the feature.

However, deploying mobile apps is not easy as for web apps or sites and with the app review you may wait 1–2 days. That’s terrible as you risk losing users.
You have to do something immediately!
With remote-controlled flags, you can temporarily disable the feature while taking your time to release the hotfix.

A/B Testing

Feature flags can be used to activate different experiences for sets of users. You can, for example, divide your user base into several sections and measure the conversion performance in order to pick the higher product conversions, engagement, growth, subscription rates, or revenue.

Product Campaigns/Early Access

Product and marketing teams can safely roll out features when they are ready, from remote. They can grant access to a feature to a group of elite users or new users to drive engagement.

Our Development Scenario

In our team, we use feature flagging to gate in-progress features so we can continue to build & test them without exposing them to end-users before they’re ready. Merge Requests are short and focused and enter into the main branch even if they are not complete yet. Obviously, they are disabled by default until everything is ready, but the team can continue the standard release cycle.

To make it effortless, at the iOS team we’ve developed an in-house opensource library named RealFlags to handle feature flags without the hassle. The idea behind the library is to use the best of new Swift language features to create a powerful abstraction layer over multiple providers you can use to setup your experiment lab.RealFlags born with Swift in mind and the vast majority of the core concepts we used to make it are introduced in the current major 5.x.

In the post below I’ll describe the architecture and the core engine with code samples and suggestions based on our experience. I should like to thank several open-source libraries who inspired the work below: [JustTweak(https://github.com/justeat/JustTweak)] by JustEat, Override by Yahoo and FeatureFlags by Ross Butler.

What you want from Feature Flags

As I said a the beginning of the post, mobile development moves quickly; the product still evolving, constraints change, your code easily becomes a legacy code you need to refactor.

Our new Swift app was born less than 4 years ago but during this period we rewrote several parts: feature flags helped us to make this process gradual. In fact, we moved from old to new implementations in a way transparent to the end user.

But a product is not only a tech affair (some devs tend for forget it). As a continuous experiment your product team would introduce new features, enable/disable existing ones via A/B testing, and so on.

So the feature flag engine must fulfill these requirements:

It’s simple — The goal is to hide the complexity as much as possible. Your team must be able to define and manage feature flags easily.In fact you should indirect encourage devs to use them.
It’s a gateway — It must act as a gateway for unfinished features. Devs/qa/product must be able to test them development process is going while the release cycle can continue with no stops.
It encourages good habits — Flags must be self-describing and easy to be organized: you may end with many different feature flags in place. The likelihood of getting lost in confusion is high and you don’t certainly want to waste your time searching where the flag is and what it means. The library itself should call on good habits.
It’s abstract — You don’t want to rely on a specific service only to waste time and resources rewriting all from the scratch when your product team will decide to move all to something else.Third-party SDKs are not under your team control and it’s different to support multiple feature flags providers.
It support different datatypes — Typically a feature flag is just a boolean value but you need to use Int, Float, String or your own structs, enum or classes! You should be able to save and set them easily.
Feature flags are discoverable — In order to simplify your dev job and allow qa/product to play with flags, you should prepare a great user interface to browse and alter values.

[RealFlags(https://github.com/immobiliare/RealFlags)] acts as an orchestration library both when you need to choose as organize your flags and how to query for values.

Introduction

RealFlags provides a simple UI to interact and modify your flags. Feature flags are organized in collections; you can define collections by using your own criteria.Once done you can add some sort of hidden menu section of your app and tell the browser to show them.

Below you can see the RealFlags menu which perfectly fits in our Developer Tools menu. This section is still visible only when the app is running in debug or from a TestFlight installation.

private lazy var shouldShowDevMenu: Bool = {
  #if DEBUG
  return true // XCode
  #else
  guard let path = Bundle.main.appStoreReceiptURL?.path else {
    return false // AppStore
  }
  return path.contains("sandboxReceipt") // TestFlight
  #endif
}()

We have different flags and we have choosen to organize them by conpetence area with a final collection dedicated to remote controlled flags.

At the time of this writing, RealFlag’s last version is 1.2.0; you can use it via CocoaPods or SPM.

Setup

It’s time to setup your stack; now you’re ready to create your first collection. Suppose you wanna make a section dedicated to the user’s experimental features.

We’ll call it UserExperiments: in this section product team can enable or disable some amazing features. Some flags may also be controlled from remote using Firebase Remote Config.

As good habit RealFlags allows you to declare the blueprint of the collection (a collection is a struct conforms to FlagCollectionProtocol) including the inner flags. While you can create collections of collections I strongly suggest to avoid it for the sake of clarity.

public struct UserExperiments: FlagsCollectionProtocol {
   // ....
   public init() {}
}

A feature flag is just a variable wrapped by @Flag decorator. Technically speaking it’s a Property Wrapper that defines all the attributes and metadata of the flag. In short, a property wrapper is a generic data structure that encapsulates read/write access to property while adding some extra behavior to augment its semantics while avoiding code duplication.

Suppose you want to create a enableSSON flag which allows the user to use single-sign-on to login inside the app. By default this flag is turned off:

public struct UserExperiments: FlagsCollectionProtocol {
   
   @Flag(key: "sson", default: false, description: "Enable Single-Sign-On")
   var allowsSSON: Bool
   
   public init() {}
}

allowsSSOn is a Bool flag which by default is false (RealFlags supports Int, String, Data, Date, URL, Dictionary, JSON and all the data types conforms to Codable) which .

The description field is used to describe the flag inside the browser so be careful when you fill it. We have also specified key: it represent the string RealFlags will use to query every Data Provider (you can configure it as you wish). You can also set more configuration parameters.

A Data Provider is just a source of data; when you query for a value of a flags, RealFlags query — in order — every provider gets the value for that key. The first one who responds with a non-nil value stops the chain with that value. If no data provider is able to respond (or you have not defined any provider) the default value is therefore returned.

Load a Collection

Since the code above it’s only a blueprint of our collection, now we need to load it. FlagsLoader is a Generic-aware class responsible to read (via mirroring) the structure of a collection.

Typically you would use a single loader to handle a single collection. When you instantiate a loader you will also specify - in order - the Data Providers you wanna use to query each flag’s value (note: you can still exclude some data providers per single flag or query a specific data provider type when you want to get the value of a flag).

Actually, you can choose two different Data Providers (but you can easily make your own as you need):

LocalProvider: it’s a writable provider. It allows you to load and set values locally inside the sandbox by just providing the URL to a file destination.
FirebaseRemoteProvider: it’s a read-only provider; allows you to get values directly from a pre-configured session of Firebase (keep in mind: your Firebase must be configured via FirebaseApp.configure() before calling this provider).

Our FFService is a simple helper class inside our app that holds the value of any loader:

public class FFService {

  public let main = FFService()
  
  public let user: FlagLoader<UserExperiments>

  private init() {
     let fileURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]..appendingPathComponent("user_flags.xml"))
     user = FlagsLoader(UserExperiments.self,
                                  description: .init(name: "User Features", description: "Experimental lab"),
                                  providers: [
                                     FirebaseRemoteProvider(),
                                     LocalProvider(localURL: fileURL)
                                  ])
  }

}

The order of the data provider in the init defines the query priority. When fetching a flag, the engine will inspect the chain of providers in order and pick the flag from the first configuration having it.

Query for values

Now you are able to query for User Experimental features by calling userExpsLoader: thanks to DynamicMemberLookup. Xcode will autocomplete for you each flag defined by the collection. Just magic!

Sometimes you may want to get the value of the flag inside a specific provider. In this case, you may refer to the projected value. We will get the value of LocalProvider by ignoring the Firebase which has a higher priority in our loader:

As we said we may have nested collections:

struct UserExperiments: FlagCollectionProtocol {
    @FlagCollection(description: "A nested collection")
    var secrets: SecretsExperiments

    @Flag(key: "sson", default: false, description: "Enable Single-Sign-On")
    var allowsSSON: Bool
}

struct SecretsExperiments: FlagCollectionProtocol {
    @Flag(default: false, description: "Risky feature!")
    var boomFeature: Bool
}

But, what’s the key queried for boomFeature? If you don’t specify the key for a flag the snake_case version of the variable name is combined with the path down to the variable itself. In this case the key queried is secrets/boom_feature.

Set Values

LocalProvider is an example of a writable Data Provider: this means you can alter a flag value and it persists between app launches.

FFService.main.$allowsSSON.setValue(true, providers: [LocalProvider.self])

Since we maintain several target applications for different countries we have used setValue() to keep a single blueprint file of definitions while altering default values inside a conditional init:

Computed flag

Sometimes you may need to create a feature flag where the value is a combination of other flags or runtime values you need to evaluate dynamically.

This is the perfect example to use the computedValue which is just a callback function called before querying any data provider. Returning a non-nil value here stops the chain.

Our suggestion is to limit the use of this pattern in order to keep the code readable. We have introduced it to handle several edge cases we have in our app.

Show the browser

We started looking at the feature flag browser. But we haven’t said how to show it. That’s simple:

In this article, I illustrated how RealFlags can be a great help in adding an abstract yet flexible approach to feature flagging.

Currently, we’re using it in our flagship product; if you want to contribute, provide additional features or providers check out the Github project page!

The economy of tech debt

2022-01-10T00:00:00+00:00

Most articles about tech debt are pretty much theory only with lots of interesting philosophies. I’d like to approach this topic in two steps:

The first part of this article is all about theory: what’s a tech debt, what’s not, and what’s the root causes and impacts on product and team.
In the second part, I’m going to give you a hands-on approach to how to manage it so you can improve your product time-to-market.

What’s Tech Debt

Tech Debt is a concept in software development that reflects the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer.

It was introduced by Ward Cunningham with the following words:

“Shipping first-time code is like going into debt. A little debt speeds development so long as it is paid back promptly with refactoring. The danger occurs when the debt is not repaid.”

So, in fact:

Is not something necessarily wrong, nor is it inherently right
It is potentially dangerous when left unpaid (it can stack up quickly and easily) This means we can accept some degree of tech debt during the development and be sure to constantly keep it in check.

What’s Not Tech Debt

It is often much easier to put all the mess under the tech debt umbrella, but there is some stuff that is not eligible as tech debt, like:

Legacy Code As long it’s tested/properly written, legacy code is boring code you should not have fun rewriting once again.
Trending Techie Don’t be such a baby; if it’s not the FoTM it’s great anyway.
Multiple Design Patterns As much as you can appreciate a common design pattern inside a product, as long as the code is properly written, it’s not a problem nor a tech debt
Code Guidelines Same of above, feel free people having some uniqueness

Measure It

Before you consider any action, you need to measure it: a good metric to evaluate tech debt and plan any action is the amount of unplanned work.

Not all of the technical debt is worth repaying Usually when the time spent refactoring exceed the benefits it’s probably a better idea to just ignore the debt (note: you should still keep the track of it, where it lays and why you have decided to not address).

Unplanned work is any task due to bugs, service interruptions, or flawed software designs.
Statistically has been shown that unplanned work should represent from 5% to 15% of the work of an organization.
When it goes higher, it should be accurately monitored in order to avoid further problems.

Root Causes

Unplanned work, and therefore tech debt, have 3 different root causes:

Time Pressure We know deadlines are part of any business. Without setting deadlines, everything is bound to collapse. However, time pressure inevitably leads to corner-cutting, which means tech debt. Beware of artificial ship dates because they lead to hidden costs.
Team Changes Teams are living creatures; they change over time (and that’s good news, indeed). When new people come into the team, they typically have steep learning curves to learn what has come before. Learning is far from perfect.
Pivots Engineering teams hate that, but pivots are a fundamental part of business reality. The alternative to pivoting is flogging a dead horse. However, pivots lead to stretching existing implementations to fit new objectives; eventually, things may break.

Mounting tech debt means spread of unmanaged complexity, resulting in less business value being unlocked.

Why?
Simpler tasks require unnecessary cognitive load, which means more [shitty] work to get done and longer delivery times. Moreover, the result is anything but good, and the situation is going to get worse once new debts are going to be added.

Impacts are on the tech side:

Performance/Stability The responsiveness and the overall stability of the application
Changeability Likelihood of introducing new defects while changing existing features or adding new ones
Security The ability of your application to prevent unauthorized intrusions

… but also for the team:

Morale The mess of tech debt slows developers down and sometimes even prevents them from doing their job. It can make it difficult to be proud of the work you’re doing as a lot of time is lost dealing with annoying problems (moreover invisible to product stakeholders).
Transferability The ease with which new developers can onboard into the product.
Retainability 51% of engineers consider quitting their job due to tech debt (read more)

Learn how to Communicate, Manage & Minimize the Impacts of tech debt in your code.

Communicate Effectively

Discussing tech debt with nontech people may be hard.

The secret here is to speak the language of business: Persuade your stakeholders that time improving the product behind the scenes will increase productivity, sustainability, and scalability.

The focus is always on cost and time instead of quality Unmanaged tech debt increase the volatility in the marginal cost of features (aka. longer development times for new/existing features).
Collect Data Measure measure measure: the number of bugs reported and accumulated per week, emergencies that occur per week, and so on. The point is to deliver your message along with measurable data. Because data are money.
Invest to save Investing 10-15% of our time in code quality help to reduce developers’ turnover. How much does it cost us to replace a leaving dev?

Make the waste visible

The difference between financial debt and technical debt is visibility. It’s not always clear how much technical debt you have at any time. A tech debt follows 3 different stages:

Unknown As you may imagine, this is tech debt that you simply haven’t identified and have no idea it even exists. Uncertainty makes this debt the most dangerous type: you can’t consider it in future tasks without knowing of its existence. This is the reason for missed deadlines, blocks, and unforeseen issues.
Dormant You know about it, but you don’t plan to address it now. You can spot this debt while working on something, eventually in some old codebase. The best thing you can do is to take a note and face it later in the distant future. It’s perfectly healthy to have.
Active You know about it, it’s defined, and you are able to plan a schedule to fix it in the foreseeable future. A common example you may incur active tech debt is when introducing a new feature following a strict deadline; the result may be less-than-ideal, but you plan actively fix it in a minor update after the release. Also, Active Debt is perfectly healthy to have.

As tech team, you’re like gardeners managing a green park along each season of the year. It’s springtime: you enthusiastically spend a large sum at the garden center and work your soil adding new plants (features) and architecting each garden (organizing your infrastructure).

Discipline is a fundamental part of your work.

You must be diligent, regularly tame and tends their urban oasis, ripping out weeds, and ultimately end up with a beautiful park (congrats, you are managing tech debts!). Failing to do regular maintenance, you eventually end up with a mess of dead plants everywhere, a dense forest, and frustration.

The goal is to make the waste visible, then schedule a plan to fix them.

Like working in a garden, software needs time and resources to keep it sustainable and avoid long-term costs.

The biggest symptom of tech debt in an average software is a specific issue or issues correlated to each other (by technical dependency) with a moderate/high occurrence-rate.

Hands-On Approach

As with any good plan, it starts measuring the impact.
You can’t plan or prioritize anything without knowing its impact.
Can’t avoid it, your job is to monitor where it is easy to find.
Once you spot it, take a deep breath and avoid fixing it immediately.
Annotate it in your backlog along with a meaningful description or a grade.

Tracking tech debts has a similar lifecycle of any product activity. Start grading your debt on 4 levels with a values between 1 (light) to 5 (heavy).

Severity: defines how much the user is disturbed/prevented from using your product. Show-stoppers or tech debt inside core parts of any foundation layer should be addressed urgently (level 5). Users rely on it, and you are likely to want to continue to develop those features. certainly, continuing to build on shaky foundations is far from an optimal solution.
Occurrence: the number of times any user encounter the issue. Be sure to correctly link the tech error with the issue (1-5 at least in the top 5 of tracking occurrences)
Dependency: How much the issue is linked to other dependencies (aka. you should also touch other parts of the code).

Now put all issues in an ordered list with those total grades.
That’s your priority.

Allocate time in each cycle

In my team, we have reserved part of any sprint (2 weeks) for addressing tech debt. The amount of this time may vary depending on a lot of factors (how big the activity is, pressure to deliver other product-related features…), but you should consider a dedicated slot (~20%) for each iteration. If you can’t commit to a fixed amount of time for each iteration, use the end of a quarter as a suitable time to do this.

Beware Artificial Deadlines

Deadlines can be real or artificial. Most of the time, artificial deadlines are used to set boundaries for all people involved. However, the hidden cost of an artificial deadline is a tech debt: while you think you can address a debt just after the release, instead, you may end up using the time supporting early changes and defects found.

Minimize Impacts

I’m sure you land in this paragraph hoping for a simple and fast answer. At this time, you should have learned you can’t avoid Tech Debt completely. It’s an inevitable part of shipping a product.

But don’t be discouraged; it doesn’t mean you can’t take some actions to minimize it:

Consistently refactoring the codebase In our team, we often joke about continuous refactoring, but a disciplined approach to refactoring leads to a codebase that is low-maintenance, highly readable as well as highly functional, all while bringing down technical debt.
A common known enemy Engineers waste more than seven hours per week on tech debt which is often invisible to stakeholders. Communicate the value of paying down technical debt to the product owner and stakeholders in your organization to make sure you have a common understanding.
Be aware of ninja devs Finding talent that can create a working solution is not enough: it is also necessary to find talent that diligently creates a solution that is as sustainable as it is functional. Be aware of the ninja devs in your team.
Encourage cross-collaboration Everyone should have a robust understanding of how core stuff works in the project; pair programming and cross-reviews must be part of the workflow.
Take time Expect to spend a chunk of time/money after each major feature release to address the Tech Debt accumulated during the push to get the feature over the finish line.
Don’t write twice MVP (Minimum Viable Product) is a critical part of each fast-moving business. You can’t afford to write things twice: produced code should be part of the product for a reasonable amount of time, so you need to make a plan even for an MVP. This doesn’t mean over-engineer; it means engineer once.

Key Takeaways

Tech Debt is an evitable output of any development activity. Not all of the technical debt is worth repaying (see time/benefits – check out this article)
Consider investing 15-20% of each iteration for maintenance and improvements requested by your team (read more)
Tracking & classification is fundamental; instill good habits in your team (read more).
Speak to nontechnical stakeholders using business terms (check out this article for some examples)
Tech Debt also impacts team morale (see “State of Technical Debt 2021”)
Propose a Tech Wealth culture in your organization

Daniele Margutti

HTTP Client for Swift

Oh no! Yet another refactor request!

Who do you talk to?

The yourney so far

The Evidencies

The Plan

One step at time

Fixing the Xcode 16 LLDB error "Couldn’t realize type of self”

p, po, v… what the heck?

How LLDB is able to format variables

swift-healthcheck to the rescue!

Where Modules come from and who register them?

The Solution

The engineer you’d want to be

The world we’re heading towards

Links

Don't hire for passion

Links

Beyond specialization

Why we need hybrid people?

To sum it up

Your thoughts

Literatures

Task & Threads in Swift Concurrency

CPU Registers

Threads

The hidden cost of threads

Swift’s Task

Threads Explosion

Literatures

The effect of indirect actions on team dynamics

How does this affect your role?

Reset the temperature

What I learned

Not everything has to be perfect the first time

Engineers and the idea of perfection

Not everything has to be perfect the first time

Conclusion

Thoughts on moving to a leadership role

Healthy approach to code reviews

Who?

Help me, help you

Small PRs is not a matter of LoC

Author POV

Reviewer POV

What you should check in a Code Review

Purpose

Implementation

Clarity

Naming & Conventions

Tests & Docs

Key Takeaways

Links

The broken window principle applied to software

An insanely detail-oriented activity

No one starts with bad intents

What Broken Window Theory Suggests

Modern networking in Swift

The Client

The Request

Configure a Request

Execute a Request

The Response

Validate/Modify a Response

Retry Strategy

Debugging

Other Features

How Feature Flags can boost your mobile app

What’s a Feature Flag?

Common Scenarios

Avoid Long-Lasting Branches

Reduce the risk

A/B Testing

Product Campaigns/Early Access

Our Development Scenario

What you want from Feature Flags

Introduction

Setup

Load a Collection