Forem: Kaww

Clean Code - Improve your code comments

Kaww — Mon, 01 May 2023 12:46:07 +0000

Robert C. Martin, often called Uncle Bob, is an American software engineer well known for his books on Clean Code and Clean Architecture.

This article is one of a series that I am writing as an introduction to Clean Code. It’s made of notes that I wrote while watching a series of video lessons that Robert gave about clean code. This one will focus on tips about code comments, from the second episode.

You can find the 6 episodes' Youtube playlist here.

Code comments

What’s the purpose of a comment? The purpose of a comment is to explain the purpose of code if the code can’t explain its own purpose.

Code can explain its purpose by itself. But it did not used to be the case: Fortran for instance have only 6 chars names for variables.

Today's languages are remarkably rich: we can have very long names, we have structs, classes, namespaces, etc. We have all the tools that we need to write code that explains itself.

Not all comments are bad

Nothing can be quite so helpful as a good comment.

Nothing can be quite so obscuring as a bad comment.

→ Comments are not “pure good”

Every comment you write is a failure

The proper use of comments is to compensate for our failure to express ourselves in code. And then because we technically can express ourselves in code, we don’t need comments.

Every use of a comment represents a failure. So don’t comment first, try everything else then comment as a last resort.

→ When you write bad code, don’t comment it, clean it.

The right colour of comments

Comments lie. Not intentionally, but as the code change, most of the time they don’t, because they are often ignored, and no one maintains them.

Comments are often in a soft and invisible colour. Change IDE settings to paint comments in bright red, so that they will be very visible. Also, this being quite ugly, it may help you to avoid writing useless comments.

→ Change IDE settings to paint comments in bright red.

Examples of bad comments

Comments that explain complex conditions or loop statements. Instead, use explanatory variables.

Read more about explanatory variables in the previous article.
Comments that reference code elsewhere (ex: \\ at this moment, {other code} should have been called).
Redundant comments that takes more time to read than time to understand the code itself.
Noise comments. For instance, comments explaining stuff that developers already know, or comments that have been copy-pasted with mistakes.
Mandatory comments. When you force developers to write comments you get stupid and useless comments. For instance, documentation comments that list all parameters of a function. Documentation tools are already smart enough to do that.

Examples of acceptable comments

Copyrights or Legal boilerplate code.
When a name is not clear but it’s named on purpose (ex: when using a design pattern or a framework), you can comment to give more context.
Informative comment: date format, regular expression, etc. But this is a double edge knife: this is very helpful while you update the comment when the code change (if not, the comment will be lying).
Warning of consequences: a function that takes time to run, or that is not thread-safe, etc.
TODO comments: a TODO means “don’t do”. You can write TODO comments but don’t commit them to Git: they have to be done. If not, they will become “don’t do” comments. A much better option if you can’t do a thing now, is to use the ticket system of your project (Jira, Notion, Trello, …) and create a technical task.
Amplification: when something is clear enough but it needs to stand out.
Documentation markups ONLY if made for external APIs. It’s acceptable for public things that are gonna be exposed to external developers. If you’re writing code that only the team is gonna see, you don't need comments, because the team knows the system.
Commented out code. If a code is not needed, remove it. You can comment code while working on something, but don’t commit it to Git. And if you are scared to lose some code, don't forget that it will stay in the Git history.

Wrap up

Here were my few notes on writing good comments from Uncle Bob’s lesson on Clean Code.

You can find my other notes on the next lessons here:

I hope this article has been helpful to you. If you have any questions or feedback about this article, don’t hesitate to contact me on Twitter!

Clean Code - Function and variable names

Kaww — Mon, 01 May 2023 12:43:31 +0000

Robert C. Martin, often called Uncle Bob, is an American software engineer well known for his books on Clean Code and Clean Architecture.

You can find the 6 episodes' Youtube playlist here.

Names

Names are everywhere: files, directories, programs, classes, variables, methods, arguments,

We then have to be good at naming!

Most of the naming rules in Bob’s videos are from Tim Ottinger’s rules for variable and class naming.

Function names should be verbs

You don’t want nouns as function names. Function names should be verbs because functions do things.

Functions names should explain clearly what it’s doing.

→ Prefer using verbs for function names.

Explanatory variables

Described in the previous article.

Some variables should exist and be named only to explain a statement. You remove the complexity of a statement (an if for instance) by explaining it with the name of the variable.

→ Extract complex statements into well-named variables.

Reveal your intent

A name that requires a comment is a bad name. The name of a variable should tell us the significance of what the variable contains.

// BAD
let d: Int // elapsed time in days

// GOOD
let elasedTimeInDays: Int

Size of names

Rules for a variable name size: a variable name should be proportional to the size of the scope that contains it :
- If the scope is very small, a single letter is fine (ex: for loops with i and j variables, you don’t want them to be any longer).
- Inside if statement, loops or small functions, it should be very short, like a word.
- In a class, instance variables have a larger scope, it should be longer, like two words.
- Global variables have a huge scope, it should be very long to be specific.
Example: a variable storing an animation duration in a very short and specific method can be named duration because the context already explains it. But the same variable in a global scope should be more detailed, like headerBounceAnimationDuration.
Rules for a function name size: the exact opposite. The bigger the scope, the smaller the name.
- We would not want to call the open function if it was called openFileAndThrowExceptionIfNotFound. We want a large scope function name to shrink because we are going to call it more, and it must be dealing with a high level of abstraction.
- An instance function of a class should be a bit more specific, it will probably have a slightly longer name.
- A private function called by a public function will have a longer name (see this article on clean code about extracting code). Then a private function called by a private function will have an even longer name…
- Names get longer because functions become more precise. It does something very tiny and precise.
Rules for a class name size: same as functions.
- Public classes have one-word names.
- Subclasses have longer names.
- Inner classes have even longer names…

→ For variables, the smaller the scope, the smaller the name.

→ For functions and classes, the bigger the scope, the smaller the name.

A good system of names

func getThem() -> [Int] {
    var list1 = [Int]()
    for item in items {
        if item == 4 {
            list1.append(item)
        }
    }
    return list1
}

This code is not complicated, but it’s not explicit. It reveals no intent.

The names do not explicitly reveal the context of the problem being solved.

func getFlaggedCells() -> [Int] {
    var flaggedCells = [Int]()
    for cell in gameBoardCells {
        if cell == CELL_STATUS.FLAGGED {
            flaggedCells.append(cell)
        }
    }
    return flaggedCells
}

Here only the names have changed. This naming system makes it easier to understand what the function does.

It also tells what program contains the function by giving context: this program is probably a game, a Minesweeper.

→ A good system of names tells you about the function you’re working on, but also about the entire context of the system.

Disambiguate

Code is full of optical illusions, and you have to fight against that.

func XYZControllerForEfficientHandlingOfStrings() -> StringController { ... }
func XYXControllerForEfficientStorageOfStrings() -> StringController { ... }

Would you pick the right function when using the code completion of your IDE?

Sometimes symbols can differ by only a few pixels.

→ Use the right names to disambiguate the situation.

Parameters with numbers

Do not use parameters with numbers, those are confusing:

func copyChars(str1: String, str2: String) { ... }

Instead, name the parameters to clarify the intent:

func copyChars(source: String, destination: String) { ... }

→ Instead of adding numbers to parameters, name them by their roles.

Use Pronounceable names

if you can’t pronounce it, you can’t discuss it.

Wrap up

Here were my few notes on naming from Uncle Bob’s lesson on Clean Code.

You can find my other notes on Uncle Bob's lessons here:

I hope this article has been helpful to you. If you have any questions or feedback about this article, don’t hesitate to contact me on Twitter!

What is Clean Code?

Kaww — Mon, 01 May 2023 12:39:51 +0000

Robert C. Martin, often called Uncle Bob, is an American software engineer well known for his books on Clean Code and Clean Architecture.

This article is the first of a series that I am writing as an introduction to Clean Code. It’s made of notes that I wrote while watching a series of video lessons that Robert gave about clean code. This one will focus on the first episode, which is an introduction to Clean Code through a few concepts that are important to know as a software engineer.

You can find the 6 episodes' Youtube playlist here.

Quotes from his friends

Here are some quotes about Clean Code that Robert’s friends gave to him.

Bjarne Stroustrup (C++):

“I like my code to be elegant and efficient”.
”Clean code does one thing well”

Grady Booch (Object Oriented Software Engineering, UML, …):

“Clean code is simple and direct. Clean code reads like well-written prose…”

Uncle Bob (Clean Code, Agile Software Development, …):

“You must write code that other people that maintain. If you hand me code that works perfectly but I can’t understand it, as soon as the requirements changes, that code is useless. But if you give me code that doesn’t work but I can understand it, I can make it work.”
“It's much more important to write code that your peers can understand, than that the computer can understand”

Ward Cunningham (Wiki concept inventor):

“You know you are working on clean code when each routine you read turns out to be pretty much what you expected...”

Why is Clean Code important?

Society works with software.

In our society today, it’s impossible to go more than 60 seconds without interacting with a software system: you can’t use a phone, watch TV, wash your clothes, you can’t buy or sell anything, …

Even your car can’t work without software: GPS, entertainment system, engine, and brakes. When you press on the breaks, there is code.

And who writes that code, that’s going to decide whether or not to stop the car when you push on the break? We write that code.

Why are programmers so slow?

Software teams want to go fast:

They write a lot of features fast at a beginning of a new project, so they make a mess. And as the mess grows they get slower.
So they need to hire more people to keep going fast. The old code teaches the new people, which continues to make a mess.
We are slow because we make a mess.

→ To work fast, work well. You are not done when the code works, you are done when it’s clean! The only way to go fast is to go well.

Function names

You don’t want nouns as function names. Function names should be verbs because functions do things.

Functions names should explain clearly what it’s doing.

→ Read more on my article on methods and variable naming.

Polite code: don’t be rude!

You have to care about developers that will read your code. So you have to make your code easy to read and understand. This is polite.

The code should read like an article

When reading the first methods names of a class (for instance the public methods) and their few lines of code, you should be able to understand in a few seconds what this code is about.

Then if you’re interested and want to go deeper into the implementation, you can continue with the next methods (for instance the private ones). You should not have to read all the code to understand what a class is doing.

→ Start with short high-level code. Code’s level is lower as you dive deeper into it.

It allows the reader to exit early.

The good size for a function

The good size for a function is when you can’t extract any other function from it.

This can be a bit extreme but the principle is still the same: a function should read easily.

So if when reading you alternate between high-level code and low-level code (like doing complex manipulations on a string and then calling a global method with this string), there is probably code that you should extract.

// high level code: publishing an article
func publishArticle(rawText: String) {
    let markdown = self.convertToMarkdown(rawText: rawText)
    self.uploadMarkdownText(markdown: markdown)
}

private func convertToMarkdown(rawText: String) -> MarkDownObject {
    // low level code: text conversion
}

private func uploadMarkdownText(markdown: markdown) {
    // low level code: network call
}

→ Every line of code in a method should be on the same level of abstraction, and that level should start right below the function name.

Explanatory variables

This is the same principle about code readability but in a deeper scope. Some code can contain complex statements that should be extracted into variables.

Reading those variable names may help the reader to understand the code faster.

// complexe if statemment
if user.isAdmin || (user.name != "" && user.address.country == "france" && user.job == "developer") {
    // ...
}

// explanatory variable
let isAdminOrFrenchDev = user.isAdmin || (user.name != "" && user.address.country == "france" && user.job == "developer")
if isAdminOrFrenchDev {
    // ...
}

→ Use explanatory variables. Their only purpose is to explain what its content is. It extracts code complexity to a “well-written prose”.

Number of arguments in a function

Reading a long list of coma-separated arguments is rude!

You probably never need to pass more than 2 or 3 things as arguments.

If you need more, like 6 things:

Those arguments are probably so tightly linked to each other that they should be an object.
Or probably some code can be extracted into 2 separate methods that only need 3 arguments each.

→ Keep the number of arguments down to 2 or 3. If you need more use other strategies: create objects, extract code, …

Don’t pass booleans as arguments

A function that takes a boolean as an argument will probably contain an if statement, that ends up with two branches in that function, for the if and the else.

Why not just separate them into 2 different functions? Call the one in the true case, and call the other in the else case.

→ Boolean arguments are often useless and can be replaced by directly calling specific methods.

Avoid switch statements

Let’s say we have a switch statement that switches on a Shape enum that declares Circles, Squares, etc.

How many switch statements do we have in our application? As many as we want to draw a shape, rotate a shape, move a shape, …
Now what happens when you create a new type of Shape? You have to go through the all code to find those switch statements to add a new case each time. This is fragile!

What we want is polymorphism.

We create a base class Shape (or an interface).
Then we create all the subclasses we need (Circle, Square, …) and put those draw(), rotate() and move methods in it.
Now what changes when we add a new Shape? We just have to create a new subclass. Nothing else change in our system.

Note: This is the “open-closed principle” (the “O” of the “SOLID” principles), which means you can add new functionalities to the system, without changing the existing code.

→ If you write the same switch statement multiple times, you should probably use polymorphism.

Side effects

What is a side effect? It’s a change in the state of the system. If you call a function that causes the system to change state, that function has a side effect.

For instance, some functions come in pairs:

File management with open and close.
Memory management with allocation and free.
Semaphores with lock and release.

Those functions cause side effects. If we forget to call the second function the state of the system stay changed.

A solution to prevent that can be to wrap those pairs of functions in a new one that doesn't have side effects.

Here is an example of a custom high-level open method in Swift that prevent side effects.

func open(_ fileName: String, lambda: (File) -> Void) {
    let file = open(fileName) // low level open method from the system
    lambda(file)
    close(file) // low level close method from the system
}

// calling this function doesn't cause any side effect
open("file.txt") { /* use the file... */ }

→ Write code that has as few side effects as possible.

Command and query separation

Commands are methods that change the state of the system. Therefore they return Void.

And by convention, a method that returns a value doesn’t have side effects.

Then when you see a function that returns a value, you know that is safe to call, it will leave the system in the same state.

If you need to return an error, instead use exceptions.

→ Follow this convention to write more consistent code.

DRY: Don’t Repeat Yourself

We don’t like duplicated code. And we don’t like code that is kind of duplicated code.

If you repeat yourself, prefer placing that code into functions. And if the repeated code changes a bit sometimes, you may want to use some sort of argument in your function to make it more flexible.

But what happens if it’s not the code that is repeated but the code structure, like loops?

For instance, let's say you have some sort of complex configuration data structure, and to work with it you have a big nested bunch of loops and if statements, then you finally get to the end node and you’ve got some processing code.

And then you see that same loop repeating inside different parts of the system.

Here again, you can use lambdas. You can put that looping structure into a function that takes a lambda as argument and then you pass the processing code into the lambda when calling that function. You can take inspiration from the way functions like map, flatMap pr compactMap works.

→ Don’t repeat yourself.

Use functions to centralise repeated code.

Use lambdas to centralise repeated code structures like complex loops.

Wrap up

Here were my few notes on this first lesson on Clean Code.

You can find my other notes on Uncle Bob's lessons here:

Lesson 2
- Functions and variable names
- Improve your code comments

I hope this article has been helpful to you. If you have any questions or feedback about this article, don’t hesitate to contact me on Twitter!

The Observer Design Pattern in Swift

Kaww — Wed, 08 Mar 2023 17:31:47 +0000

In this article, we will learn what is the Observer design pattern and how to use it.

The use case

Let’s say we have a weather station that regularly takes measures of temperature and humidity:

struct WeatherData: Equatable {
    var temperature: Int
    var humidity: Int
}

class WeatherStation {

    private var timer = Timer()
    private var lastMeasurement: WeatherData? = nil

    init() {
        self.timer = Timer.scheduledTimer(withTimeInterval: 2, repeats: true, block: { [weak self] _ in
            self?.measureWeather()
        })
    }

    private func measureWeather() {
        // Simulate new data
        let newData = WeatherData(temperature: Int.random(in: 0..<10), humidity: Int.random(in: 0..<10))
        if newData != lastMeasurement {
            self.lastMeasurement = newData
        }
    }
}

And two screens that are connected to the station, one displaying temperature, the other one displaying humidity:

struct TemperatureScreen {
    func display(temperature: Int) {
        print("Temperature is now \(temperature)")
    }
}

struct HumidityScreen {
    func display(humidity: Int) {
        print("Humidity is now \(humidity)")
    }
}

→ How would we allow the several screens to update their information when the weather changes?

Polling the data?

One solution that can come to mind would be that a screen can regularly ask the weather station for new data, for instance, every 100 milliseconds.

Unfortunately, this won’t be very efficient. Here is why:

If the weather doesn’t change during a minute, all screens would ask a lot of times the weather station for nothing, wasting energy.
The more screens you have, the more the weather station will receive simultaneous requests, which risks to overload the station.

So instead of making the screens asking the new data, let’s try to see the solution in the other direction: what if it’s the weather station's responsibility to inform the screens of new data?

The observer pattern

The observer pattern is based on two elements:

The observable (also called the subject): the object that is observed, the weather station.
The observers (also called subscribers): they observe the observable. The screens observe the weather station.

The responsibility of the observable is to keep a list of its observers and notify them if needed. Then, the observers can register or unregister themselves from the observable.

We can see that like a newsletter: a person can subscribe to a newsletter, and the newsletter system will notify each subscriber when new information is available.

Let’s see what the Swift code would look like.

The code

First, we have to define the two protocols: the observable and the observer

Observable

The observable is composed of:

A list of subscribers, of the type WeatherStationSubscriber (we will come to that).
A register method, that we can call to add subscribers. An unregister method should also be added to stop a subscription.
A notify method that will be used to notify the subscribers.

protocol WeatherStationObservable {
    // 1
    var subscribers: [WeatherStationSubscriber] { get }
    // 2
    func register(_ subscriber:  WeatherStationSubscriber)
    // 3
    func notify(_ newData: WeatherData)
}

Let’s apply that to our weather station:

We add the WeatherStationObservable protocol conformance to our WeatherStation.
We declare the list of subscribers.
We implement the register method, by adding the new subscriber to the list of subscribers. Note that you may want to prevent the same observer to subscribe multiple times, by checking before if the subscriber is already in the subscribers, or by using a Set instead of a list.
Finally, we implement the notify method: we just have to iterate through each of the subscribers and notify them with the new data.

class WeatherStation: WeatherStationObservable { // 1

    // previous code ...

    // 2
    var subscribers: [WeatherStationSubscriber] = []

    // 3
    func register(_ subscriber: WeatherStationSubscriber) {
        subscribers.append(subscriber)
    }

    // 4
    func notify(_ newData: WeatherData) {
        for subscriber in subscribers {
            // TODO: notify subscriber here !
        }
    }
}

Now we just have to modify the measureWeather method to call the notify method:

private func measureWeather() {
    // Simulate new data
    let newData = WeatherData(temperature: Int.random(in: 0..<10), humidity: Int.random(in: 0..<10))
    if newData != lastMeasurement {
        self.lastMeasurement = newData
        self.notify(newData)
    }
}

Observer

The observer (here we call it subscriber) is even easier: it just has to implement a method that can be called by the subscriber to notify it when new data is available:

protocol WeatherStationSubscriber {
    func onNotified(_ newData: WeatherData)
}

Let’s apply that to one of our screens:

Here the onNotified method will just send the temperature information to the display method.

struct TemperatureScreen: WeatherStationSubscriber {

    // Previous code...

    func onNotified(_ newData: WeatherData) {
        display(temperature: newData.temperature)
    }
}

Usage

Now let’s see how to use that in practice:

We create the weather station.
We create the screens.
We register the screens to the weather station.

// 1
let weatherStation = WeatherStation()

// 2
let temperatureScreen = TemperatureScreen()
let humidityScreen = HumidityScreen()

// 3
weatherStation.register(temperatureScreen)
weatherStation.register(humidityScreen)

The final code

import Foundation

struct WeatherData: Equatable {
    var temperature: Int
    var humidity: Int
}

protocol WeatherStationObservable {
    var subscribers: [WeatherStationSubscriber] { get }

    func register(_ subscriber:  WeatherStationSubscriber)
    func notify(_ newData: WeatherData)
}

protocol WeatherStationSubscriber {
    func onNotified(_ newData: WeatherData)
}

class WeatherStation: WeatherStationObservable {

    private var timer = Timer()
    private var lastMeasurement: WeatherData? = nil

    var subscribers: [WeatherStationSubscriber] = []

    init() {
        self.timer = Timer.scheduledTimer(withTimeInterval: 2, repeats: true, block: { [weak self] _ in
            self?.measureWeather()
        })
    }

    private func measureWeather() {
        print("Measuring...")
        let newData = WeatherData(temperature: Int.random(in: 0..<10), humidity: Int.random(in: 0..<10))
        if newData != lastMeasurement {
            self.lastMeasurement = newData
            notify(newData)
        }
    }

    func register(_ subscriber: WeatherStationSubscriber) {
        subscribers.append(subscriber)
    }

    func notify(_ newData: WeatherData) {
        for subscriber in subscribers {
            subscriber.onNotified(newData)
        }
    }
}

struct TemperatureScreen: WeatherStationSubscriber {
    func onNotified(_ newData: WeatherData) {
        display(temperature: newData.temperature)
    }

    func display(temperature: Int) {
        print("Temperature is now \(temperature)")
    }
}

struct HumidityScreen: WeatherStationSubscriber {
    func onNotified(_ newData: WeatherData) {
        display(humidity: newData.humidity)
    }

    func display(humidity: Int) {
        print("Humidity is now \(humidity)")
    }
}

let weatherStation = WeatherStation()

let temperatureScreen = TemperatureScreen()
let humidityScreen = HumidityScreen()

weatherStation.register(temperatureScreen)
weatherStation.register(humidityScreen)

Now if we run that code in a playground, we can see each time the weather station gets new data, it will notify the screens that will display the new weather information:

Measuring...
Temperature is now 7
Humidity is now 3

Measuring...
Temperature is now 1
Humidity is now 9

Measuring...
Temperature is now 4
Humidity is now 8

Wrap up

In this article, we learned what is the observer design pattern and how to use it.

I hope this article has been helpful to you. If you have any questions or feedback about this article, don’t hesitate to contact me on **Twitter!

How to create an example app for your SPM package

Kaww — Wed, 08 Mar 2023 12:57:55 +0000

When working on a Swift package, it may be quite difficult to test that the code we are writing works properly.

Beyond writing unit tests, an easy way to test a package would be to configure a demo project right inside the repository. This has non-negligible advantages:

It allows us to write at the same place the package code and the demo code without any friction.
It allows us to configure several targets, for instance, an iOS and macOS demo apps.
It serves as documentation code with usage examples for other developers that will be able to browse the code on Github.

In this article, we will see how to add and configure a demo app project for an SPM package.

Create the demo project

First, we need a Swift package. If you don’t have any and want to learn how to create one, check out my article “How to create an SPM package with SwiftUI”.

Now we will create the demo app project. In Xcode, go to File > New > Project...then choose for instance an iOS app. By convention, I will name it as my package name suffixed by “demo”. Here, “MyPackageDemo”. Some also suffix it "Example".

Then save the project at the root location of the Swift package:

Close Xcode windows, then go to the new Xcode project directory and open the .xcodeproj file.

Configure the demo project with the package

The trick here is to import the SPM package by referencing its location on the disk, instead of importing it from GitHub.

To do so, go to the main project file then go to Project > Your project > Package Dependencies.

Press the “+” button and select “Add local”. The Finder opens, go to the root location of the SPM package, where the Package.swift file is (and that now also contains the demo project folder).

The SPM package is now imported, we can see it in the file explorer section.

The final step will be to link the package’s library to our demo project target. To do so, go to the main project file then go to Targets > Your project target > General. Scroll down to find the section Frameworks, Libraries, and Embedded Content then click the “+” button.

A window opens, find the SPM package and select the library icon.

All good! The project is fully configured, it's now possible to compile both the package code and the demo app, simply by changing the build target on Xcode’s top bar.

We can now use our package's code in our demo app's code and push all that on the package’s GitHub repository.

Note that if you want to work in that configuration, you need to open the .xcodeproj file with Xcode. And if you just want to open the SPM files you can still open Xcode at the package's root location, but you won’t be able to run the demo app this way.

Wrap up

In this article, we learned how to create and configure a demo app project for an SPM package to simplify its development.

I hope this article has been helpful to you. If you have any questions or feedback about this article, don’t hesitate to contact me on **Twitter!

How to create an SPM package with SwiftUI

Kaww — Wed, 08 Mar 2023 12:43:31 +0000

Swift packages are reusable components of Swift, Objective-C, Objective-C++, C, or C++ code that we can import into any Xcode project.

In this article we will see:

How to create our Swift package containing reusable SwiftUI code
How to make it available for other developers
How to add our new package to an Xcode project

Create our package

In Xcode, go to File > New > Package….

Name the package, select a destination to save the project and click the “create” button. The package is created.

The package contains several default files:

README.md is a markdown file that will serve as documentation for other developers.
Package.swift contains the configuration of the package.
MyPackage.swift is the default generated file. We won’t use it as we will create another one.
MyPackageTests.swift is also generated by default and is made for unit testing for the package. We will not cover that part today.

Configure the package

We can see that the file contains some information about the package, like its name, its products (the parts that other developers will import into their projects) and the targets for compilation. It also contains a dependencies section if the package needs to import other Swift packages.

As SwiftUI only runs on iOS 13 or later (also macOS but we will not cover that), we need to add this requirement to our package.

Add the following property under the name property:

let package = Package(
//    name: ...
    platforms: [
        .iOS(.v13)
    ],
// ...
)

Adding our code

Create a new file next to MyPackage.swift file to write our SwiftUI code. For this tutorial, we will use this code:

import SwiftUI

public struct MyPackageView: View {
    public init() {}
    public var body: some View {
        Text("Hello world in MyPackage!")
    }
}

Note that all here needs to be marked as public. If not, nothing will be visible for developers that will import your package.

📝 While developing a package, it may be useful to be able to run the code we are writing on a demo app.
Check my article How to create an example app for your SPM package!

Make the package available for other developers

To make this new package available for other developers, we will need to host it somewhere. Here we will use Github.com.

On Github, create a new repository. Add a name and use all the default settings. Just make sure the repository is public.

Now open the terminal at the location of the project directory and enter the following commands:

git init
git add --all
git commit -m "first commit"
git branch -M main
git remote add origin YOUR-PACKAGE-URL
git push -u origin main

→ Here you need to replace the YOUR-PACKAGE-URL by the URL of the Github repository. In my case it’s https://github.com/Kaww/MyPackage.

The package should now be available!

Import the package to an Xcode project

Now we may want to use our new package in an Xcode project. Let’s see how to import it.

Open an Xcode project, go to the main project file then go to Project > Your project > Package Dependencies.

Press the “+” button and enter your package Github URL in the search bar.

We can specify a dependency rule like a minimum version number for the package (if we added a release in the Github repository). Here we will use the code available on the main git branch.

Then press “Add Package”.

We can see that your package appeared on the file explorer under the “Package Dependencies” section.

In a SwiftUI view, we can now import the package and call the view we created:

Add import MyPackage on the top of the file.
In the view, add MyPackageView() to call the package’s view.

And that’s it!

Wrap up

In this article, we learned how to create a Swift package and what are the important files in it.

Then we learned how to push it on Github to make it visible and available for other developers.

Finally, we’ve seen how to import the package as a dependency for another project to use its code.

I hope this article has been helpful to you. If you have any questions or feedback about this article, don’t hesitate to contact me on **Twitter!