If you’re a developer who wants evergreen guidance instead of the flavor‑of‑the‑month framework book, start here.

“The best way to predict the future is to create it.”
— Abraham Lincoln.

I believe most skills are acquired through hard work and discipline. And that successful people have a track record of applying these.
To become a better version of yourself, you must find room to grow and fill it. By learning, by trying, by deciding to no longer tolerate your limitations.

One guaranteed way to learn and grow is by studying the great books from a certain domain. I’ve compiled a top list of Software Development books, books that were simply transformational. When it comes to learning, I prefer a proven track, so I mostly focus on timeless classics instead of following trends and the most recent publications. These are mostly books that offer depth, explaining ideas, concepts, paradigms, techniques, patterns. Most of them are platform and language agnostic, so they are applicable to Software development in general.

Disclaimer: I recommend studying these books, and learning from them, not just reading. This means reading more than once, taking notes, trying out the concepts in real life, trying to link the new knowledge to the one you already have (to make learning effective).

Format: I tried summarizing the book in one paragraph, define the book’s impact on me and listing my main takeaways.

Dependency Injection in .NET by Mark Seeman

This book offers a thorough explanation of how to decouple software components by injecting their dependencies at runtime, enabling more flexible, testable, and maintainable code in applications.

For me, it has transformed the way I design and code apps, deeply understanding layering and dependencies, modularizing (based on the requirements), but also having a proven mechanism (Composition Root) to compose modules into different apps or flavors of the same app.

Takeaways:

• Manual DI: Constructor, Property or Method Injection.
• Constructor Injection is the safest option in compiler-based languages, as the compiler won’t allow constructing an object unless its dependencies are provided.
• Service Locator anti-pattern - widely used pattern which leads to high-coupling and can generate runtime errors when dependencies are missing.
• Choosing between Manual DI vs DI containers (the later should not be used in all app layers, but rather in the Composition Root only).
• Modularity and how to compose an app using modules and a Composition Root.
• Composition Root pattern = the lowest level and most concrete component, the app entry point.
• How to implement Cross-Cutting concerns with the Decorator pattern.

Working Effectively with Legacy Code by Michael Feathers

If you’re a developer, you work with legacy code. This book highlights the high value of existing, functioning code and shows how to make small adjustments to make it testable and unlock refactoring.

This book transformed the way I look at code, especially legacy code. From running away from legacy code and being intimidated by such challenges, it flipped the narrative and allowed me to see all the opportunities to improve that already functioning code, following these battle-proven techniques and patterns. Having these skills makes me stand out as an engineer.

Takeaways:

• Legacy code = code without tests or with an unclear structure, regardless of age.
• Use the recipes in the book to make small safe changes that enable testability.
• Seam = place where you can alter behavior without modifying existing code directly - essential for introducing tests and making controlled changes.
• Write Characterization Tests for legacy code which enable safe refactorings.
• Sprout Method / Class - instead of modifying an existing method or class, you “sprout” a new one that safely holds new functionality.
• Wrap Method / Class: Wrapper around existing entity to intercept or adjust behavior without changing the original one.
• Breaking Dependencies - see techniques for dealing with problematic dependencies (like singletons, static methods, or global variables) so that you can isolate and test the units in question. Often involves introducing interfaces or employing DI.
• Extract and Override Call: Move direct dependency call (e.g., to a difficult API) into separate method that you can override in a subclass, avoiding the real dependency in tests.
• Extract Interface: Split an existing class into an interface and an implementation; the interface can then be mocked or substituted as needed.
• Parameterize Constructor or Method: Let the constructor / method accept external dependencies (instead of hard-coding them).
• Pull Up / Push Down Feature: Move a field or method from derived classes into a base class when it is shared logic; move the other way to isolate specialized behavior.
• Extract Method: Pull out piece of logic from a larger method into a separate one.

Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans

This book emphasizes structuring and implementing software around a deep understanding of the business domain, using a Ubiquitous Language and well-defined boundaries to create models that reflect real-world complexity effectively.

This book is incredibly deep, with very subtle but powerful concepts and examples. It made me push for a unified language between all the stakeholders involved in Software Development. And it enhanced the awareness I keep on the domain model and its separation from other layers.

Takeaways:

• Focus on the Core Domain: Invest time and resources in the core domain (business strategic advantage) and model it with precision and clarity.
• Iterative Model Refinement: Continuously refine the model as new insights emerge, using ongoing collaboration and domain exploration to keep it aligned with real-world needs.
• Align Design and Implementation: Ensure that code structure reflects the domain model and that the model is kept in sync with the code - refactor the code to keep up.
• Ubiquitous Language
  • A shared language between domain experts and developers.
  • Ensures everyone speaks consistently about the model, preventing misunderstandings.
• Bounded Context
  • A boundary within which a particular domain model applies.
  • Helps avoid confusion due to overlapping or duplicated concepts across different parts of the system.
• Associations
• Entities, Value Objects, Aggregates, Services
• Repositories, Factories, Domain Events
• Anti-Corruption Layer
• CQS at domain model level

Refactoring: Improving the Design of Existing Code by Martin Fowler

Refactoring is not rewriting; it’s a methodical process of cleaning up code with recipe-like steps. Think of this as the classic “recipe book” for refactoring.

I use it regularly, especially given the IDE I mostly use (Xcode) has very limited automated refactoring capabilities. The most transformative concept for me was deeply understand what refactoring is and trying to refactor as much as possible ever since - of course, by preserving the code behavior.

As Kent Beck explained it, a developer can wear multiple hats, only one at a time. Changing functionality is done under a different hat than refactoring. Making this separation I believe to be making your output so much clearer.

Takeaways:

• Incremental Improvements: effective refactoring happens in small, safe steps:
  • make one change at a time
  • run tests
  • and proceed only if the system remains stable.
• Code Smells indicate where to refactor - e.g. Long Method, Large Class, Primitive Obsession, Switch Statements, Divergent Change, Shotgun Surgery.
• Automated Testing Is Essential: Having robust unit and integration tests enables you to refactor with confidence.
• Refactoring Preserves Behavior: The goal is to change the structure, not the functionality; if system behavior changes, that’s not a pure refactoring.
• Refactoring Improves Maintainability: Well-structured code is easier to understand, modify, and extend, ultimately saving time and effort in the long run.
• Composition Over Inheritance: Wherever appropriate, prefer using composition to extend functionality rather than complex class hierarchies; this often reduces coupling.
• Encapsulate What Varies: Identify aspects of the code that might change or expand over time and encapsulate them (e.g., through design patterns like Strategy or Decorator).
• Replace Conditionals with Polymorphism: Frequent if / else or switch statements can often be replaced with polymorphic classes or methods to simplify control flow and make code more extensible.
• Naming Matters: Consistent and meaningful names for variables, methods, and classes help communicate intent and maintain clarity.
• Continuous Refactoring Culture: Treat refactoring as an ongoing, integral part of development rather than a one-time event—this keeps code healthy over its entire lifespan.

Clean Code: A Handbook of Agile Software Craftsmanship by Robert Martin

Clean Code emphasizes writing readable, maintainable, and elegant code by following core principles, best practices, and disciplined craftsmanship that leads to higher-quality software.

Reading Clean Code and Clean Coder was the point in time where I stopped being a “hacker” (in the sense of hacking things together so they work) and moved towards being a professional developer, that follows standards, metrics, rules, that takes pride of their work. In my case, it was an identity transformation.

Takeaways:

• SOLID principles: applying all the 5 principles is fundamental to writing maintainable, readable, testable code.
• Readability Is Key: Code should be optimized for human comprehension first, ensuring that anyone can easily understand and modify it in the future.
• Small, Focused Functions and Classes: Methods and classes should do exactly one thing and do it well, which keeps the codebase modular, testable, and easier to maintain.
• Meaningful Names: Clear, descriptive naming for variables, functions, and classes significantly reduces confusion and improves overall readability.
• Continuous Refactoring: Regularly improving existing code keeps it clean and up to date, preventing “code rot” and complexity from creeping in over time.
• Emphasis on Testing: Testing (often through TDD) helps catch issues early and ensures the code’s design stays simple, robust, and reliable.
• Error Handling: Handle errors gracefully and clearly. Use exceptions for exceptional conditions and provide context in error messages.
• Code comments: Favor self-explanatory code over excessive comments. Use comments sparingly to clarify complex logic rather than to explain poorly written code.
• Comments show our inability to express ourselves through code.
• Formatting and Consistency: Follow consistent formatting rules to help others (and your future self) navigate the code easily.
• Boy Scout Rule: Leave the camp cleaner than you found it.

The Clean Coder: A Code of Conduct for Professional Programmers by Robert C. Martin

The Clean Coder emphasizes the ethics, mindset, and practices that distinguish professional programmers, focusing on responsibility, discipline, and clear communication to produce high-quality software.

Takeaways:

• Professionalism as a programmer, Standards and Accountability
• Clear communication and Boundaries
• Discipline in Coding Practices: TDD, Refactoring, CI
• Handling timelines, pressure, estimations
• Continuous Learning and Improvement

Clean Architecture: A Craftsman’s Guide to Software Structure and Design by Robert C. Martin

Clean Architecture describes principles and design practices for creating software systems that are resilient to changing requirements, easily testable, and maintainable over their entire lifecycle.

Takeaways:

• Separation of concerns
• SOLID Principles in detail, at the method, class and module levels.
• Entities
• Business rules
• Usecases
• Frameworks and drivers
• Layers and Boundaries
• Plug-in Architecture

iOS Unit Testing by Example: XCTest Tips and Techniques Using Swift by Jon Reid

This is a practical guide to writing maintainable and robust iOS applications through effective unit testing and test-driven development (TDD) principles, focusing on both Swift and Objective-C codebases.

Automated testing is such a complex domain and it requires so many other skills to be put to practice. More so TDD. It’s one thing to write some unit tests and another to choose between numerous types of tests, write clean concise tests, that exercise the behavior of the code and not its structure so that one can later refactor that code without breaking the tests. With the help of this book and the iOS Lead Essentials program by Caio and Mike, I was able to take my testing skills to the next level. I became proficient with testing, capable of thinking strategically about testing strategies and their implementation using various types of tests.

Takeaways:

• TDD encourages Clean Code
• Clear test structure improves readability: use patterns like Arrange-Act-Assert (AAA) and give tests descriptive names
• Using test doubles are essential skills: mocks, stubs, fakes
• Continuous testing boosts confidence: run these locally, while you develop, after every change. Also run them as part of the CI pipelines
• Well-written, high-coverage tests serve as a safety net for refactoring, encouraging developers to improve design without fear of breaking existing functionality.

The Pragmatic Programmer: Your Journey To Mastery by Andrew Hunt and David Thomas

The Pragmatic Programmer provides practical guidance and a mindset for software developers to continually refine their craft, create robust solutions, and take ownership of all aspects of their code.

This book may seem trivial in some ways, but it has a subtle intelligence to it. It highlights an art of being balanced, pragmatic, of choosing wisely between quick and dirty and clean elaborate solutions. It highlights the need to be focused so you can choose from all the tools at your disposal. And it does a great job at showcasing many of these tools that were here many years ago when it was first published.

Takeaways:

• Embrace continuous learning.
• Adopt a pragmatic mindset over dogmatic rules.
• Focus on clean design and DRY: minimize duplication, promote reusable components, and favor simplicity to reduce complexity.
• Take ownership and responsibility: Take pride in your work, own the quality of your code, and be proactive in identifying and fixing potential problems or misunderstandings.
• Refactor early and often.
• Orthogonality and decoupling: Strive for independent components whose functionality does not overlap, making your system more adaptable, maintainable, and testable.
• Tracer Bullets: Implement thin, end-to-end solutions to test architecture and feasibility early, guiding further development through continuous feedback.
• Prototyping: Build quick, disposable implementations to explore ideas, verify assumptions, or confirm feasibility without committing to production-quality code right away.
• Design by Contract: Define clear, enforceable contracts for functions, modules, or services (preconditions, postconditions, and invariants) to ensure correct behavior.
• Automation: Invest in tools that automate repetitive or error-prone tasks (testing, builds, deployment) so you can focus on high-value work.
• Coding Conventions and Standards: Maintain consistent naming, formatting, and architectural decisions to improve team collaboration and readability.
• Collaboration and Communication: Write clear documentation, engage in effective code reviews, and communicate openly with team members to address issues early and improve collective knowledge.

Extreme Programming Explained: Embrace Change by Kent Beck

Consider this the field manual on Extreme Programming (XP) and Test Driven Development (TDD). XP is a lightweight, people-centric methodology that emphasizes rapid feedback, short development cycles, close collaboration, and continuous improvement to deliver high-quality software in the face of changing requirements.

Takeaways:

• Core XP Values: Communication, Simplicity, Feedback, Courage, Respect.
• TDD: Writing automated tests before coding to guide design and validate functionality. Uses a Red - Green - Refactor cycle.
• Pair Programming: Two or more developers share one workstation, continuously reviewing and improving each other’s work. Produces quality design, less defects, reduces need to use the classical code review workflow.
• Continuous Integration: Frequent merging of code changes to identify integration problems early.
• Refactoring: Systematic improvement of code structure without altering functionality.
• Simple Design: Always aim for the simplest system that works, deferring complexity until necessary.
• On-Site Customer: Having a real customer or representative available for immediate feedback and clarification.
• Collective Code Ownership: Any team member can modify any part of the code at any time.
• Whole Team: All roles (developers, testers, domain experts) collaborate continuously.
• Sustainable Pace: Avoid burnout by maintaining a healthy, consistent work pace.

Feedback

What are the books that have changed the way you work, the way you think? What’s your favorite learning from them?

What book from this list are you planning to read next? Why?

Let me know in the comments section. I’d be happy do discuss and learn from you too.

• What is source control and how it works
• What is git and how it works
• The main git entities
• What are git hosting services
• The main git commands and flows

What is source / version control

Version control, also known as source control, is the practice of tracking and managing changes to software source code. Version control systems are software tools that help software teams manage changes to source code over time. They do this by recording the changes to files over time.

Why? Because the source code is an important asset for any team, so protecting it is essential. Source control systems allow:

• Backing up code
• Having a history for each individual file, so we can go through each of these versions. The source control history is a piece of documentation that is updated along with the source code and ideally tracks and explains the reasons for each change made to the code
• You can preview previous states and decide to revert some or all the files to such a previous state
• Teams can parallelize development by allowing different members to work on different tasks (features, bugs, …). Source control allows integrating all these independent modifications to the code.
• Comparing and tracking changes over time, identify the exact time when a change was introduced and why

What is Git

By far, the most widely used modern version control system in the world today is Git. Git is a mature, actively maintained open-source project originally developed in 2005 by Linus Torvalds, the famous creator of the Linux operating system kernel. A staggering number of software projects rely on Git for version control, including commercial projects as well as open source.

At the root of the git system is the concept of a repository. The repository is used to store different files and folders in a tree structure, like a miniature file system.

Most version control systems store the information as a list of file-based changes. Git works differently, as git organizes its data like a set of snapshots on a miniature file system. These snapshots are called git commits. Every time you create a new commit, you basically save the state of the project files in git and create a reference to that state. That is what a commit is. Git is efficient and if some files have not changed from a previous snapshot, it will only link to the previous identical file it has already stored. You can think about it as a stream of snapshots.

Text and binary files

Git is very efficient in working with text files, such as source code files, plists, jsons, string files … This is because it can calculate the differences between text files and even apply compression to store them very efficiently. Diff is a shorter version of difference, and we will use this term further to describe the differences between 2 versions of the same file. Git can handle other non-text file types as binary files (images, videos, libraries, …), but it can’t apply the same optimizations as for text files. Storing many binary files, especially large ones, can impact the performance of git. If that happens, you can look into the git large file system extension that is designed for large binary files.

Why git?

Simply because git is:

• Distributed
  • Each developer has a clone of the whole repository
  • Offline access
  • Multiple back-ups
  • No need to share unwanted changes - you can keep some changes local until they are ready
  • Sharing is easy
• Fast
  • Nearly all operations are performed locally → no need to constantly talk to the server → very fast
  • Git uses gzip compression
  • The only operation that is slower is the initial clone operation, where git is downloading the entire history of the repository
• Preserves the integrity of the files
  • The data model that Git uses ensures the cryptographic integrity of every bit of your project.
  • Every file and commit is checksummed and retrieved by its checksum when checked back out.
  • It’s impossible to get anything out of Git apart from the exact bits you put in.
• Supports non-linear development
  • Git allows and encourages you to have multiple local branches that can be entirely independent of each other.
  • Keeps multiple streams of work independent of each other while also providing the facility to merge that work back together, enabling developers to verify that the changes on each branch do not conflict.
  • Creating, merging and deleting these lines of development takes seconds.
• Scalable
• Simple, Free and Open source

Git hosting services

Git is a version control system that can be viewed as a tool. To store git repositories, we need hosting services. These are called git hosting services, and they act like servers that host git repositories among other things (e.g. user-based access and permissions, repo statistics, …). Famous ones include: GitHub, Bitbucket, GitLab.

In a simplified scenario, git can be used entirely locally on just one machine, but its greatest power is when it’s used across machines.

Most people will use git as a server - client, where one git server like GitHub will act as the single source of truth. All the clients will pull code from the server, make local changes and push the modified code to the same server. But that’s not the only way in which git can work. Being a distributed system, each machine having a copy of the repository can act as a server for other machines.

Main Git entities

Repository

The repository is a data structure that stores files and folders and corresponding metadata. This metadata is saved in a special .git folder and is represented by all the versions of these files and folders over time. Or you can look at a repository like a collection of commits. Each client will have a full copy of the repository.

Working copy

The working copy is a single checkout of one version of the project. These files are pulled out of the database in the .git directory and placed on disk for you to use or modify.

Commit

The commit is a snapshot of your working copy at a certain time, identified by a revision number (hash). Besides the snapshot, it contains info such as the author, the date, and time and a message describing the changes done. Each commit can have from zero parents (the 1st commit in each repo), to 1 parent (linear structure) to more than 1 parent (where a merge was done).

Branch and tag

While for many version control systems, branches and tags are full copies of the repository content, in git, branches and tags are just commits with a name attached to them. That is why it’s trivial to create / remove branches or even to update them aka change the commit with the name. The same is true for tags, even though git tag commands are a bit more restrictive. From a theoretical standpoint, a branch supports an independent line of development. It has a lifetime, when the developers will use the branch to develop independently of other branches, commit their work and in the end, port their changes back to one of the main branches.

In contrast, a tag is a label we attach to a version of the project that we want to preserve with time, so we can revisit later. For example, releasing a new version of the project is a good time to create such a label, so you know exactly the state of the source code used for that release. So in that line, tags are not meant to be modified.

HEAD

The HEAD is the name of the commit that’s currently checked out. In git, you can check out any commit at any time. Checkout means simply setting the repo files in the state of the commit you select.

Git commands

Git uses many commands with different options that allow a multitude of operations. Any tool you use would still rely on these commands under the hood: Git clients like Xcode’s git integration, SourceTree, GitHub’s Mac App, … Or even editing the repo through a website (i.e. GitHub’s web interface) They all work with the same git commands and show the same info from git.

Config

When you first install git on a machine, you need to configure it. Configuring git can be done through the git config command or by directly editing a file ~/.gitconfig. Using the commands will edit the same file we just mentioned. You can at least set up your git username and email.

git config --global user.name "John McClane"
git config --global user.email "john@email.com"

Creating a new repository

To create a new local git repository, we will use the git init command in the folder that we want to be the root folder of the repository. This will just initialize the git repository by creating a .git folder with some basic info. The repository is empty, there are no commits, no branches or other entities yet.

Hosting services like GitHub also have an option to create a new repository. Using this option will require you to answer a few questions like the name and location of the new repository and if it needs any template files like README or LICENSE. GitHub will create a new repository on its backing git system. It will also create a first commit with all the files you chose to create. And a branch called main. To use this new repository, you need to clone it on your machine.

Cloning a repository

By using the git clone <URL> command, one can clone aka fully copy a repository on his / her machine. You require this to be able to make changes to the repository. For the cloning to work, you will need permissions to that repository. There are 2 main types of cloning - via HTTPS or SSH.

Via HTTPS

Using an HTTPS url like https://github.com/bpoplauschi/bpoplauschi.github.io.git will set up an HTTPS connection to the repo, so it will require a user and password authentication in order to clone it and for all future communications with the git server.

Via SSH

Using a SSH url like git@github.com:bpoplauschi/bpoplauschi.github.io.git will create an SSH connection which requires an SSH public - private key pair that is used for authentication. You will need to set up your machine so it allows SSH connections to services like GitHub by creating a local SSH key pair or installing a key pair from another machine - see Connecting to GitHub with SSH. The public key needs to be added to your GitHub account, so the service has it so it will allow your connections using the private key. You can easily verify your SSH setup is correct by running ssh git@github.com.

In either case, you need read access to the repository or just a public repository to perform the clone.

Now that you have a local repository (either by cloning or creating a new local repo), you can start editing it.

Status

You can always inspect the status of the repo using the git status command - this will output the current checked out branch and local changes, both non-staged and staged.

Staging area

After you make changes to the files in your repository, you will need to commit those changes into the repository. Git has a so-called “staging area” that is an intermediate area where commits can be formatted and reviewed before completing the commit. You can add and remove to and from stage entire files or just some modified lines. git add Some git tools (like Xcode’s git integration) will not show you the staging area, but it’s useful to know it’s there. When you commit, you will commit all the content added to the staging area.

NOTE: any change to a file that is not committed can be lost if we change branches, merge, reset, … Only after we have committed, we are confident the data is safely stored in our repository. So commit as often as possible - this will help you avoid losing precious code.

NOTE: you can always drop changes and go back to the previous git state using different commands. One such command is git reset –hard that will undo all the local changes from the current HEAD.

Diff

Moreover, you can view at any time a diff between the current head (currently checked out commit / branch) and the local changes made after that. git diff or git diff --cached for staged changes.

Committing

To save progress on our changes into the repository, we will create commits. This assures our changes are safe and can be retrieved later if needed. git commit -m “Message” This will create a new commit on the current branch with the message included and containing all the content from the staging area. A good practice we encourage is to make small commits where we change only a few files and that has a single reason for change.

Checkout

You can always checkout any commit (aka get the repo files in the state they were at that commit): git checkout <COMMIT_HASH> Note that checkout will result in all the files tracked by git being replaced with their version from the commit you are checking out. If you have local changes, you will need to do something with them (like commit), before you can checkout a different commit.

Log

To inspect the current git history using the command line, the simplest option is to use: git log or git log --all --decorate --oneline --graph Or you can just use a git client with UI where we can visually inspect commits, branches …

Branching

Remember, branching is useful to support multiple lines of development. A good practice is to create a branch for each line of development:

• For each feature or partial feature
• For each bug or fix
• For each refactoring
• For each idea you try out The big advantage is we can seamlessly switch from one branch to another and come back. Using git branches allows us to:
• work on a feature
• then create a different branch for a bug fix we need to solve now
• then switch to another branch to review a colleague’s work
• and return to the branch for our feature with little to no cost.

If we have a repository created using a git hosting service like GitHub, it will have a main branch by default. You can create as many other branches as you want without extra costs to the repo, as you know, branches are just names given to particular commits. You can create a branch using git branch <BRANCH_NAME> You can list all the existing branches using git branch (add -v for extra info)

Git allows and encourages you to have multiple local branches that can be entirely independent of each other.

You can switch between branches using git checkout <BRANCH_NAME> This is very fast. After you’re done with the work for a feature / bug / experiment, you can decide to share this branch with others or just discard it.

Merge

Merging is Git’s way of putting a forked history back together again. The git merge command lets you take the independent lines of development and integrate them into a single branch.

So from 2 different lines of development, we can use git merge to combine them into a single branch, usually we develop on a feature / bug branch and then merge back to our default branch - in this case main. Merge is important because from the time we start a branch from main until we integrate back to it, other branches might be integrated as well, so we have to combine all these changes together. Sometimes, if the different lines of development change the same files, at merge we will see conflicts (these cannot be automatically resolved by git) that we must resolve on our own.

Local vs remote

All these operations like initializing an empty repository, creating commits, creating or switching branches and even merging branches are local operations, and they don’t require a connection with a git service.

But we work in teams, so we usually store the git repositories on a service like GitHub, which means this is the central repository where everyone gets the latest changes from and where they upload their changes.

Git is designed to give each developer an entirely isolated development environment. This means that information is not automatically passed back and forth between repositories. Instead, developers need to manually pull upstream commits into their local repository or manually push their local commits back up to the central repository.

Remotes

So, a git remote is an external location that has a copy of the same repository we have locally. We can use git commands to pull changes from this remote or to push our changes. And using a git interface, we can compare the local state of the repo to the remote ones.

We can inspect the remotes on each local repository using git remote –v If we have just a local repository (created using git init), we will have no remotes here.

If we have cloned the repository from another location, we will usually have one remote called origin.

NOTE: we can add / remove / edit these remotes and have more than 1 at a time.

Remote branches

As soon as we have a remote set up, git can access the branches from that remote. For example, using git branch -va will show all the branches, local and remote.

Fetching changes to remote branches

The git fetch command downloads commits, files, and branches from a remote repository into your local repo. Fetching is what you do when you want to see what everybody else has been working on. But this is only informative, no changes will be applied to our local branches.

Pulling

The git pull command is used to fetch and download content from a remote repository and immediately update the local repository to match that content. Merging remote upstream changes into your local repository is a common task in Git-based collaboration workflows. The pull command is actually a combination of two other commands, fetch followed by merge. git pull = git fetch + git merge

Pushing

The git push command is used to upload local repository content to a remote repository. Pushing is how you transfer commits from your local repository to a remote repo. It’s the counterpart to git pull, but whereas pull imports commits to local branches, pushing exports commits to remote branches.

Pull Requests / Merge Requests

A Pull Request is a concept that exists only on GitHub (also called Merge Request on other services). From a git’s perspective, there are no pull requests. These features exist on git hosting services like GitHub, and they make it easier for developers to collaborate. Using a branch shared with other developers (this can be the main branch, a develop branch), you pull the latest changes so the main / develop branch is up-to-date. Before making changes to it, you branch from it - creating a new local branch, then make some changes, push back the changes by creating a remote branch from your local branch. And now you want to integrate these changes back to the main / develop branch. Usually, these branches are protected by GitHub, so you can’t push directly to them, so instead you express your intention of pulling your changes into the main / develop branch by creating a Pull Request. The Pull Request object exists only on the GitHub service, your local git repository has no notion about PRs. Other developers on your team can review your PR, comment, and request changes. When it’s approved, the PR can be merged using GitHub’s interface, which will result in a merge commit on the main / develop branch that merges the new branch you created back into its original branch. This is a regular git merge, only created by GitHub. So, you have to pull from the main / develop branch to get this.

Forks

Services like GitHub have many features, among which is a very detailed and granular access control. A project’s admin can allow some users to read / fetch the repo’s contents but not push to it (read-only) while only a few have write / push permissions. GitHub has public repositories that can be read by every user and private repositories that limit the users that can access them. To facilitate collaboration between users, GitHub and other services have the option to Fork a repository. When a user forks a repository, he creates their own server-side copy of that repository. The difference is the user has full access to their fork repo. So, they can create branches, delete branches, push and pull code. Forks are really useful when you want to contribute to repos where you don’t have push permissions. If you have forked a repository, you can track it locally via a new remote (besides the origin one pointing at the main repository). GitHub and other services allow creating PRs on the main repository from branches pushed to forks. Once the team maintaining that repo approves the PR and merge it, your changes will be integrated into that central repo - just like any other merge operation.

Ignored files

Git will ignore files or folders that follow certain conditions of name or path. These regex filters can be added in a .gitignore file contained in each repo and in a ~/.gitignore_global file that exists under your Mac local account and affects all repositories. Make sure what you add to these files, as the files and folders matching these patterns will be entirely ignored by git. While the .gitignore file is checked in the repo and will affect all the other repo copies, the .gitignore_global is local to your machine and this can make git behave differently on your machine than on others.

Recap

Recommendations

Every team will have its preference. It’s up to you to decide, but here are our recommendations:

Commit as often as possible

We recommend you make small commits, as often as possible. Then commit should modify only a handful of files, and it should have one very specific reason / goal. Make sure you describe this reason in the commit message.

These commits will act like checkpoints you can go back to when things get messy. Don’t rely on UNDO, or you’ll lose work. It’s similar to playing a video game, you want to save often, so you can continue from a safe state which is very close to the current one.

Moreover, consider these commits might be reverted if the change turns out to be temporary or inappropriate. So make your commits with this in mind. It’s very hard to partially revert a large commit.

Write good commit messages

It’s essential to write descriptive and clear commit messages describing the intent of the changes, not the actual implementation. For example, it’s clear from the code that we are adding 2 new functions to a class. What is not clear is why we are doing it. Git commit messages will serve as a documentation for all the changes made to the source code and the reasons for these changes.

Tag releases

It’s very useful to use tags to mark the commit representing each release you make, whether it’s internal or external. It will also add context to your repo, of all the releases you made. And when a problem occurs in a previous release, you can checkout and inspect exactly the state of the code you used for that release.

Periodical clean up

Make a habit of cleaning up git. Delete unused branches, both locally and from the remote repo.

References

• Git Documentation
• Git Reference (all commands)
• Git Tutorials and Training by Atlassian
• Git Cheat Sheet by GitHub

Let’s take a quick look at how I structured this info:

• Definitions: what is a library, what is a framework, what is linking, what do static and dynamic linking mean (Part 1)
• iOS and macOS linking differences (Part 1)
• Implications of using static vs dynamic on app binary size and launch time
• The most common ways to integrate 3rd party code and how static vs dynamic linking applies to them

Before jumping in to the more advanced topics of dynamic vs static linking, make sure you know what’s the difference between a library and a framework, between a static framework and a dynamic one, what does the linker do, … Read Part 1 - Introduction to static and dynamic, libraries and frameworks on iOS (and macOS) before continuing.

Summary of static vs dynamic linking

App Size

• smallest app size when using the macOS dynamic linking + sharing your dynamic modules separately (instead of embedding them into the app)
• using static linking results in a smaller app size than using dynamic embedded modules (the compiler can optimise by excluding unused symbols)
• biggest app size: using dynamic linking + embedding the modules in the app (the compiler cannot optimize, all the symbols have to be included)

App Launch Time

• statically linked modules are fastest to load (loading non-system dynamic frameworks is pretty expensive while system frameworks are optimized). When using static linking, all the symbols are within the same module, so the app start is fast.
• dynamically linked modules are slower to load, especially on iOS. Known issue: loading dynamic modules is expensive, especially at start time. Apple recommended in WWDC to use a max of 6 dynamic frameworks. See details in the iOS increased App Launch Time section below.
• I didn’t find any reference of a limit of dynamic frameworks for macOS apps, probably because Macs have better hardware and this is no longer an issue. But even here, static linking will probably result in a quicker app start.

Safety (of symbols existing at runtime)

• All the code linked statically is checked and copied at build time, so we have the guarantee it works. The client code can’t get out of sync with the library APIs.
• iOS - even if the modules used by the app are checked by the compiler, one can simply forget to embed them, resulting in a crash at runtime Library not loaded ... Reason: image not found
• macOS + shared modules: since we relly on resolving dependencies at runtime, we add extra risks. The dependencies might not exist or, exist, but have a different version than we expect. Both situations could result in a crash.

Independent deployment

• Static linking: everything is delivered in one app binary, so there’s no way to deploy just some dependencies / modules.
• iOS doesn’t allow independent deployment of libs / frameworks.
• macOS: if modules are installed at a shared location (like the system ones), there’s the posibility to deploy and update them independently of the apps using them.

When to use dynamic linking

So if statically linked modules result in a smaller app size and are faster at loading, why would we want to use dynamically loaded modules?

Here are a few situations.

Sharing libraries / frameworks on macOS

When you want to share the same binary (library / framework) between multiple apps, you can install it in a shared location and use it as any other system dynamic module.

Multiple static modules depending on the same module

Let’s say you have a module (your own or 3rd party) named Common that is used by other modules in your app. FeatureA -> Common and FeatureB -> Common. If FeatureA, FeatureB and Common are static libraries / frameworks, you’ll see a warning at app runtime in the console duplicate symbol MY_COMMON_SYMBOL in ... FeatureA and ... FeatureB. This happens because when linking statically to Common, both FeatureA and FeatureB binaries will contain the symbols from Common. So at runtime, the loader will not know which one is should use.

In this case, unless you have other things to consider, making Common a dynamic module will solve the problem, as both FeatureA and FeatureB will just reference Common, expecting at runtime to find an implementations for its symbols.

iOS increased App Launch Time when using many dynamic libs / frameworks

I’ve mentioned using many 3rd party dynamic libraries / frameworks probably leads to an increased app launch time on iOS.

This was detailed in WWDC 2016 Session 406 - Optimizing App Startup Time (I can only find the transcript of that session on asciiwwdc). Apple explained how each dynamic module adds to the total app launch time and we should keep the number of dynamic modules to a max of 6. See Apple’s Reducing Your App’s Launch Time article that mentiones all of that, except for an exact number of dynamic frameworks (perhaps over time the 6 limit became harder to keep and, since hardwares evolved, the limit might have increased).

The matter is simple: just test it out. Older Xcode versions required adding DYLD_PRINT_STATISTICS to the ENV variables to print stats regarding the app launch time and how much each step took. See Apple’s Logging Dynamic Loader Events. Looks like this:

Total pre-main time:  95.07 milliseconds (100.0%)
         dylib loading time:  25.00 milliseconds (26.3%)
        rebase/binding time:  19.75 milliseconds (20.7%)
            ObjC setup time:   6.85 milliseconds (7.2%)
           initializer time:  43.45 milliseconds (45.7%)
           slowest intializers :
             libSystem.B.dylib :   8.43 milliseconds (8.8%)
   libBacktraceRecording.dylib :   9.00 milliseconds (9.4%)
    libMainThreadChecker.dylib :  22.05 milliseconds (23.1%)

Or you can use Instruments, as explained in Apple’s Reducing Your App’s Launch Time article.

Please consider there are 2 types of app starts Cold App Start and Warm App Start. A cold start is when you app starts for the 1st time (after a phone reboot) and is usually the slowest start. After that, even if you close the app, the system will cache some of the memory footprint (in case you closed the app by mistake). The next time you start the app will be a faster, warm start. So to measure reliably, measure your app launch after a phone reboot (cold start).

If you find your app is taking a long time starting (Apple recommended 500 miliseconds for a seamless user experience), take a look at what is holding your app from launching. It can be many things, as executing some code on the AppDelegate or SceneDelegate methods, having a huge Launch storyboard, … If the problem lies with dylib loading time, you can look into changing some dynamic libraries / frameworks to static ones.

Should you want to dig deeper into this issue, there’s a very good thread on a GitHub open source app called Eigen by Artsy: https://github.com/artsy/eigen/issues/586

Static / dynamic with different integrations techniques

Since nowadays many projects have a lot of 3rd party dependencies, let’s look at how these dependency managers work and how we can control their linking related behavior.

Own targets or projects linked directly

If the targets are in your repo or in other repos, but are linked to your project, you can go in and change the way they are built and linked through Build Settings.

You just need to change the value of the MACH_O_TYPE Build Setting between Static Library (staticlib) and Dynamic Library (mh_dylib).

To change between a library and a framework, you need to change the type of Product the target outputs (not sure how to do that from settings, but I find it easiest to just create a new Framework target and moving everything inside it).

CocoaPods

By default, CocoaPods (no mention of use_frameworks!) will build and link all the dependencies as static libraries.

If we add use_frameworks! to our Podfile, CP will instead build and link the dependencies as dynamic frameworks.

We can use use_frameworks! :linkage => :static to make CP build and link dependencies as static frameworks.

See https://guides.cocoapods.org/syntax/podfile.html#use_frameworks_bang.

NOTE: of course, all these apply to dependencies that CocoaPods builds from sources. If you are referencing a pod that is precompiled, there is no way for CocoaPods to change how that pod is packaged. Most packages distributed as precompiled binaries will be static libraries or static frameworks.

Swift Package Manager

SPM does not allow any control over how the dependencies are build and linked - they are all static libraries. You can, however, specify how to build your own packages via Package.swift where you can specify type: .dynamic, but of course, this works only if you are the maintainer of that package.

Carthage

By default, Carthage uses dynamic frameworks to build your dependencies, but there is an option to change them to be built and linked statically.

Conclusion

As you might have deduced already, there’s no silver bullet and you have to choose what applies best to each situation. What is important is that you understand the impact your decision has.

Make sure to check out Differences in Dynamic & Static Frameworks/Libraries by EssentialDeveloper, that does a great job going through some real examples and explaining what each setting does / changes.

When building apps on any platform (Apple platforms included), we have to deal with system frameworks, packaging our own code, using 3rd party code and many more. Many developers work with static and / or dynamic frameworks / libraries, but don’t fully understand them, and thus, can’t get the best out of them. So I decided to share my knowledge, hoping I can help clarify these notions.

Let’s take a quick look at how I structured this info:

• Definitions: what is a library, what is a framework, what is linking, what do static and dynamic linking mean
• iOS and macOS linking differences
• Implications of using static vs dynamic on app binary size and launch time (Part 2)
• The most common ways to integrate 3rd party code and how static vs dynamic linking applies to them (Part 2)

Before diving in, let’s clear up the terminology we use: we will refer to libraries and frameworks from a point of view of packaging and linking.

Another angle of looking at library vs framework looks at flow control: your code calls libraries, frameworks call your code (after registering with them). We don’t care much about this second interpretation for now.

What is a library

A library is a collection of non-volatile resources used by computer programs. This can include source code. Most of the libraries we see for macOS or iOS contain code (compiled for one or more architectures). Libraries can be linked statically (called static libraries) or dynamically (dynamic libraries). We’ll look at what linking means in a few.

When trying to ship resources (like string files, images, …), iOS / macOS libraries are delivered together with bundles containing these resources. I don’t know of a way to include resources in iOS / macOS libraries.

Examples

Static libraries usually look like lib*.a files, for example: libGoogleAnalytics.a (you might have used this one). Dynamic libraries use the *.dylib extension.

What is the (CPU) architecture

In the context of iOS / macOS compiled binaries, the architecture refers to the CPU architecture. We need to compile our binaries for all the different CPU architectures they will be used on.

Currently, macOS has support for two architectures:

• x86_64 the architecture of Intel’s 64-bit CPUs. It is the architecture for all Intel Macs shipped between 2005 and 2021.
• arm64 is the architecture used by newer Macs built on Apple Silicon (2020+).

iOS simulators run on macOS, so they use the same architectures.

iOS supported more architectures over time:

• Old iOS devices shipped before 2009 had armv6 CPUs, which are no longer supported by current iOS SDKs.
• armv7 an older variation of the 32-bit ARM CPU, as used in the A5 and earlier.
• armv7s being used in Apple’s A6 and A6X chips on iPhone 5, iPhone 5C and iPad 4
• arm64 is the current 64-bit ARM CPU architecture, as used since the iPhone 5S and later (SE, 6, 7, …), the iPad Air, Air 2 and Pro, with the A7 and later chips.

You can see the architecture(s) set for an Xcode target by looking at Build Settings -> Architectures (ARCHS). It’s preset by Xcode to Standard Architectures (on Xcode 12.5 and an iOS target, this resolves to arm64 armv7).

What is a framework

A framework is a package that can contain resources such as precompiled code (libraries), string files, images, storyboards etc. (if it contains other frameworks, it’s called an umbrella framework). Apple’s frameworks are organized into bundles (have a predefined folder structure on disk). They can be accessed via Bundle class from code and, unlike most bundle files, can be browsed in the file system (easy for developers to inspect the contents).

Check out Apple’s Bundle Programming Guide.

Frameworks are also bundles ending with .framework extension. Note: With Xcode 11, Apple added xcframework extensions, also bundles with multiple architectures and platforms.

Static framework

A framework that embeds a static library has to be linked statically, so we call it a static framework.

Dynamic framework

A framework that embeds a dynamic library has to be linked dynamically, so we call it a dynamic framework.

Umbrella framework

A framework embedding other frameworks inside. It is not officially supported on iOS and that is why it is not recommended for developers to create them Official doc.

Example

They all look like *.framework folders, for example: FirebaseAnalytics.framework (you might have used this one).

Linking

A linker or link editor is a program that takes one or more object files (generated by a compiler or an assembler) and combines them into a single executable file, library file, or another “object” file.

Usually, the linking phase happens right after the compilation phase, and even if they are different and executed by separate components, we simplify by referring to both processes together as “compiling” or “building”.

If you look at a build log, you’ll see that a section like “Build target MyApp” contains several steps, one is probably “Compile Swift source files” and soon comes “Link MyApp” (if you expand the Link command, you’ll see a Ld ... long command).

Dynamic linking

Many OS environments allow dynamic linking, deferring the resolution of some undefined symbols until a program is run. Shortly, dynamic linking means adding references from one module (your app) to another module (library / framework). This dependency will be provided and resolved at runtime. This is the way most system frameworks work - when building your app with UIKit, the app binary references UIKit, but doesn’t include its symbols. The system “knows” a version of UIKit will be available at runtime (and uses dyld to load it). This version is shared by all apps and is delivered as part of the OS.

Of course, there is a possibility the referenced binary doesn’t exist on the system, so trying to resolve it will result in a crash. I haven’t seen this happen on iOS or macOS, but people using Windows may remember the msvcrt.dll was not found crash, especially when playing games (an example of dynamic linking gone bad).

Static linking

Static linking is the result of the linker copying all the module’s (library / framework) routines used by the app into the executable. An advantage of static linking is the linker can determine which symbols are needed by the app and only include these (instead of all the symbols from the module).

Static and dynamic linking on iOS / macOS

Static linking on iOS / macOS is very similar to other platforms - the linker will copy all the symbols needed by a binary into that binary. This means copying all the symbols that your app needs from other (static) modules into your app binary.

Dynamic linking on macOS

Dynamic linking on macOS is also similar to other platforms, where the OS has shared dynamic libraries / frameworks and users can install their own dynamic modules too and share them between apps.

Dynamic linking on iOS

On iOS, all the system modules are linked dynamically. Examples: Foundation, UIKit, CoreGraphics, libsqlite, …

This means they are shared by all apps and each OS version has an embedded version of these modules.

What is different from other platforms is there is no way for a developer to install their dynamic modules in a shared location and use them from different apps. This is because apps run in a “Sandbox” and cannot install modules to other parts of the system.

The impact of this limitation is that you can use dynamic modules, but you have to embed them in your app’s binary.

Embed modules in the app binary

By choosing to embed a module in your app (Target - General - Frameworks, Libraries, and Embedded Content), you enable the Embed Frameworks Build Phase that copies the modules into your app binary (the .app will contain a Frameworks folder with them).

How to find out if a library / framework (3rd party) is static or dynamic

If you are looking at a binary library / framework (perhaps it’s precompiled by a 3rd party) and want to know if it’s a static or dynamic binary, just use file command with the path to the binary file. Example (static framework) - static binaries are usually marked with ar archive or similar.

file FirebaseAnalytics.framework/FirebaseAnalytics 
FirebaseAnalytics.framework/FirebaseAnalytics: Mach-O universal binary with 2 architectures: [arm_v7:current ar archive] [arm64:current ar archive]
FirebaseAnalytics.framework/FirebaseAnalytics (for architecture armv7):	current ar archive
FirebaseAnalytics.framework/FirebaseAnalytics (for architecture arm64):	current ar archive

Example (dynamic framework) - usually mentioned dynamically linked

file SDWebImage.framework/SDWebImage              
SDWebImage.framework/SDWebImage: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit dynamically linked shared library x86_64] [arm64:Mach-O 64-bit dynamically linked shared library arm64]
SDWebImage.framework/SDWebImage (for architecture x86_64):	Mach-O 64-bit dynamically linked shared library x86_64
SDWebImage.framework/SDWebImage (for architecture arm64):	Mach-O 64-bit dynamically linked shared library arm64

Final thoughts

This should give you a better understanding on what libraries and frameworks are and how they are linked. If you want to dive deeper, Part 2 of this article deals with more advanced concepts like the impact on dynamic / static linking on performance, how dependency managers deal with these and more.

1. Traits of a Clean architecture

There are different variations of architectures that are considered clean, but they all have the following characteristics:

• Independent of frameworks

  The architecture does not depend on the existence of some library of feature-laden software. This allows you to use such frameworks as tools, rather than forcing you to cram your system into their limited constraints.

• Testable

  The business rules can be tested without the UI, database, web server, or any other external element.

• Independent of UI

  The UI can change easily, without changing the rest of the system. A web UI could be replaced with a console UI, for example, without changing the business rules.

• Independent of the database

  You can swap out Oracle or SQL Server for Mongo, BigTable, CouchDB, or something else. Your business rules are not bound to the database.

• Independent of any external agency

  In fact, your business rules don’t know anything at all about the interfaces to the outside world.

2. Onion-layer diagram

• Enterprise Business Rules represented by Entities
  • agnostic of app
  • apply to the entire business domain
  • have no dependencies
• App Business Rules represented by Use Cases or Interactors
  • apply to the application domain
  • can depend on Entities
• Interface Adapters: Controllers, Presenters, Gateways, …
  • depend on Use cases / Interactors
• Frameworks and drivers: Devices, DB, Web, UI, …
  • depend on the rest of the system

NOTE: The arrows (dependencies) always point inward, so the frameworks and drivers depend on the rest of the system, but nothing else depends on them.

3. SOLID Principles

3a. Single Responsibility Principle

A module should have one, and only one, reason to change.

can be rephrased as

A module should be responsible to one, and only one, user or stakeholder.

The simplest definition of a module is a source file.

Why is SRP important:

• leads to small components
• that are easy to read and composable
• avoid conflicts

SRP is different than the lower level principle of refactoring large functions into smaller ones (aka a function should do one thing).

The best way to understand this principle is by lookign at the symptoms of violating it.

Symptom 1 - Accidental Duplication

Let’s imagine an Employee class with 3 methods: calculatePay, reportHours and save. This class violates the SRP because those 3 methods are responsible for 3 very different actors:

• calculatePay is specified by the accounting department, which reports to the CFO
• reportHours is specified and used by the HR department, which reports to the COO
• save is specified by the DBAs, who report to the CTO

By putting the source code for these three methods into a single Employee class, the developers have coupled each of these actors to the others. This coupling can cause the actions of the CFO’s team to affect something that the COO’s team depends on. Let’s assume the calculatePay function and the reportHours function share a common algorithm for calculating the non-overtime hours. The developers will naturally extract that common algorithm into a function regularHours called by both calculatePay and reportHours. When one team (for example the CFO’s team) needs to change the regularHours algorithm, they will affect (and possibly break) the reports the COO’s team is generating.

Symptom 2 - Merges

Merges usually happen in source files that contain many different methods, especially likely if they are responsible for different actors. For example, the CTO’s team of DBAs wanting to change the schema of the Employee table and the COO’s team of HR clerks want to change the hours report formatting. This means at least 2 developers will make changes to the same file at the same time, probably resulting in a conflict that requires a merge.

Merges are risky affairs, even if we now have tools that handle some cases, we will still end-up with having to resolve conflicts. Unless we really understand what the other team changes are, there’s a good chance we won’t resolve the conflicts properly and introduce issues.

Solutions

There are many different solutions to this problem. Each moves the functions into different classes.

The simplest and most obvious one is to separate the data from the functions. So we create the Employee Data, PayCalculator, HourReporter and EmployeeSaver classes, now the last 3 classes that have encapsuled different pieces of logic are separated from each other.

The downside is that now developers need to instantiate and track all 3 classes. A common solution for this dilemma is to use the Facade pattern by creating an EmployeeFacade that will act as a proxy to each of the dedicated classes.

3b. Open / Closed Principle

A system should be open for extension but closed for modification.

OCP is interconnected with SRP and DIP. When we make sure each class has a single responsibility (SRP) and we make it depend on abstractions instead of concrete types (DIP), OCP quickly follows. Now it’s easy to create new implementations of the abstractions and inject them without having to change the initial class.

OCP is gained by following all the other principles.

Adding new features should be done by adding code / components and changing very little of the existing ones.

Why is OCP important:

• makes the system changeable and testable
• keeps changes contained to one part of the system

Example 1

Classic example: we want a screen that displays a list of feed items.

FeedViewController depends on an abstraction FeedLoader. We can have as many implementation as we want:

• at first, mock with dummy data
• remote that fetches the data from the network
• local that loads from local storage
• even a composed remote with fallback on local variant

We can compose the FeedViewController with any of them, while it remains closed for modifications, but open for future extensions.

Example 2 - Enums

Enums break OCP because the client code needs to be updated on every change to the enum. The Router code is coupled with the current enum cases and is also a dependency magnet, as it references 3 concrete types.

enum DeeplinkType {
    case home
    case profile
    case settings
}

protocol Deeplink {
    var type: DeeplinkType { get }
}

class SettingsDeeplink: Deeplink {
    let type: DeeplinkType = .settings

    func executeSettings() {
        // Presents the Settings Screen
    }
}

class Router {
    func execute(_ deeplink: Deeplink) {
        switch deeplink.type {
        case .home:
            (deeplink as? HomeDeepLink)?.executeHome()
        case .profile:
            (deeplink as? ProfileDeepLink)?.executeProfile()
        case .settings:
            (deeplink as? SettingsDeeplink)?.executeSettings()
        }
    }
}

Using polymorphism makes the Router agnostic of which Deeplink type is it really handling. Router is closed for modification but open for extension - we can easily add or remove Deeplink implementations without affecting any of the existing code.

3c. Liskov Substitution Principle

Derived classes must be substitutable for their base classes.

Any of MockFeedLoader, RemoteFeedLoader, LocalFeedLoader, … can be used and FeedViewController must work just fine.

Another example: UIPageViewController or UINavigationController work with any APIs that require a UIViewController (because they subclass it).

Why is LSP important? It Allows composing the components in any way we want / need.

3d. Interface Segregation Principle

Make fine grained interfaces that are client specific.

Don’t make clients depend on details they don’t need!

Why is this principle important:

• We end up with smaller interfaces which are composable
• Less code dependencies, especially when they are not needed

A common violation of ISP is creating interfaces with many functions, some optional or unneeded by their clients.

One reason for wanting segregated interfaces is to avoid source code dependencies that are not needed (thus requiring more time to compile and the need to redeploy a bunch of modules on a very small change to just one of them).

Example

protocol GestureProtocol {
    func didTap()
    func didDoubleTap()
    func didLongPress()
}

Splitting a 3 methods GestureProtocol into 3 individual ones, thus allowing clients to conform to 1, 2 or all those protocols without having to add empty method implementations. Also, a class like MyButton can have different properties for each action type (i.e. a tapHandler property of type TapProtocol and a doubleTapHandler property of type DoubleTapProtocol).

protocol TapProtocol {
    func didTap()
}

protocol DoubleTapProtocol {
    func didDoubleTap()
}

protocol LongPressProtocol {
    func didLongPress()
}

class MyButton: UIButton {}

extension MyButton: TapProtocol {
    func didTap() { ... }
}

extension MyButton: DoubleTapProtocol {
    func didDoubleTap() { ... }
}

We can implement those protocols in multiple classes or just one, but MyButton is agnostic of those details.

Counterexamples

Apple’s frameworks often break ISP by having protocols like UITableViewDataSource or UITableViewDelegate with many methods not needed by most of their clients.

Also, they mix together multiple concepts like data source, prealoading, styling, …

3e. Dependency Inversion Principle

Depend on abstractions, not on concretions.

High-level modules should not depend on low-level modules both should depend on Abstractions. (Abstractions should not depend upon details. Details should depend upon abstractions).

We apply DIP to most of our dependencies, especially volatile ones.

Why is DIP important:

• The system is easy to compose diferently
• Low coupling (as we are not bound to concrete types)

There are always cases where we will need to depend on concrete types - can’t make everything into an abstraction. No problem, refactor later.

One very useful application of DIP is to protect our business code from (3rd party) frameworks. Instead of making our code depend on a framework, we create an abstraction and depend upon it. Then the framework will conform to that abstraction, thus inverting the dependency (Inversion of Control).

protocol FeedLoader {
    typealias Items = [FeedItem]
    typealias Result = Swift.Result<Items, Error>
    func loadFeed(@escaping (Result) -> Void)
}

class FeedViewController: UIViewController {
    private let loader: FeedLoader
    
    init(loader: FeedLoader) {
        self.loader = loader
    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        ...
        let items = loader.loadFeed()
        ...
    }
}

// URLSession based loader
class RemoteFeedLoader: FeedLoader {
    // ...
}

// or, even an Alamofire based loader
import Alamofire
extension SessionManager: FeedLoader {
    // ...
}

4. Composition over inheritance

Inheritance

Inheritance: “is a” relationship.

Inheritance is the highest form of coupling.

Inheritance breaks encapsulation (allows subclasses to access internal details).

The compilation time and run time for inheritance is bigger, because of virtual tables.

Inheritance is resolved at compile time.

Composition

Composition: “has a” relationship.

Composition is resolved at runtime (you can compose your types differently depending on platform / environment / …).

To achieve low coupling, prefer composition.

This doesn not mean avoid polymorphism (which is a strong programming tool), but rather separate responsibilities into small entities that are composed, also keeping them clean of inherited behavior / interface.

// inheritance
class Device {
    let name: String
    let operatingSystem: String
}

class Smartphone: Device {}
class Computer: Device {}

// composition
protocol SystemProtocol {
    var operatingSystem: String { get }
}
protocol Nameable {
    var name: String { get }
}

struct Smartphone: Nameable, SystemProtocol {
    var name: String
    var operatingSystem: String
}
struct Camera: Nameable {
    var name: String
}

5. The Main component aka Composition Root

In every system, there is at least one component that creates, coordinates, and oversees the others. We call this the Main Component or, it’s also known as the Composition Root pattern.

The Main component is the ultimate detail - the lowest-level policy. It’s the initial entry point of the sytem. Nothing, other than the operating system, depends on it. It’s job is to create all the Factories, Strategies, and other global facilities, and then hand control over to the high-level abstract portions of the system.

You can have multiple Main components: one for each configuration, platform or target.

The Composition Root is made of many components (Factories, Adapters, Decorators, …).

Why is the Composition Root important?

• It’s where we define how our system should operate (depending on the conditions)
• We can deal with low level concepts here (current configuration, platform, device vs simulator, target, …)

6. Frameworks are just details

As the Clean Architecture “onion layers” diagram shows, frameworks live at the outer boundary of the system because they are just details. Clean systems should not depend on one or more frameworks becase:

• coupling the business code with framework details makes it harder to write, read and test
  • just think about frameworks that ask you to subclass their classes
• the frameworks often change with a different agenda than our project’s
• if the system is coupled with the frameworks, this change is very hard to do
• they should allow us to switch between one framework to another

Examples:

• you should be able to easily change your data storage from in memory, local file storage, UserDefaults, Keychain, CoreData, SQLite, Realm, … or a combination of them
• changing the UI of the app should be easy and require just changes to the UI layer: from UIKit to SwiftUIor even a simple Command-Line tool without UI
• functional / reactive frameworks (Combine, RxSwift, … ) should be interchangeable and decoupled from the business layers - used only in the CompositionRoot because of the way they offer out-of-the-box patterns for Adapters / Factories / …
• same for networking: URLSession, Alamofire, AFNetworking, Moya, …

Postpone the decision about which framework / library to use for as much as possible - so you have as much info as possible.

You can use test doubles (mocks or stubs) and you have a low coupling with the actual framework.

7. Handling many 3rd party dependencies

It’s become very normal that iOS projects have a lot of dependencies, especially 3rd parties.

• We need a networking component, but not sure what we need from that component? No problem, just add a 3rd party.

• We want to do “analytics”? Sure, add a few more 3rd parties.

• Here’s a cool utility belt library - add it!
• Need a draggable table view cell? Of course there’s a library for that.

Before you know it, your project has a dozen of those dependencies, most likely through different dependency management systems (manual, git submodules, SPM, CocoaPods, Carthage), it takes a large amount of time to clone the project and build it.

A few problems with this approach:

• you’re adding a lot of uncontrollable risks: each library has it’s own roadmap, hidden issues, …
• what do you do when a 3rd party project is abandoned or doesn’t fix the most outstanding issues you have?
• having so many dependencies + a lot of them are not designed for a modular and testable integration results in very hard to test code

I recommend you:

• limit the number as much as possible
• postpone the decision
• protect from them by inverting the dependencies and make the 3rd parties depend on your code.

8. UI layer patterns - a classical iOS debate

MVC, MVVM, MVP, VIPER are just design patterns for the UI layer. They don’t solve the problem of who should handle many other responsibilities like: business rules, data access and storage, notifications, navigation and deeplinking, … Evem though our community is constantly debating which pattern is best and new ones keep coming out, there’s hardly any evidence for it. Indeed, certain patterns are better matches for specific constraints:

• for example, MVC is better suited for UIKit components as they are already built around the UIViewController subtypes
• MVVM seems to fit better when working with SwiftUI

8a. The issue of massive components

But none of those patterns will protect us from the problem of Massive components. Massive View Controller can quickly become Massive View Model or Massive View Presenter. Clean architecture principles help us better separate our code into components and avoid this issue.

9. Cross-cutting concerns

Examples: threading, logging, authentication, analytics, security …

Those concerns are usually spread through the codebase and they are duplicated most of the time.

Example - threading

class MainQueueDispatchDecorator: FeedLoader {
    private let decoratee: FeedLoader
    
    init(decoratee: FeedLoader) {
        self.decoratee = decoratee
    }

    func load(completion: @escaping (FeedLoader.Result) -> Void) {
        decoratee.load { result in
            if Thread.isMainThread {
                completion(result)
            } else {
                DispatchQueue.main.async {
                    completion(result)
                }
            }
        }
    }
}

When composing the FeedViewController, we can pass an instance of MainQueueDispatchDecorator as a FeedLoader, while keeping all the FeedLoader implementations clean of threading.

Example - analytics / logging

Instead of having each ViewModel do analytics or logging, we can decorate the ViewModel with analytics / logging behavior, keeping it clean of this cross-cutting concern.

10. References

• iOS Lead Essentials program - Online program meticulously thought out for iOS developers who want to become world-class senior developers and be part of the highest-paid iOS devs in the world. Focuses on key concepts like Swift, TDD, BDD, DDD, Clean Architecture, Design Patterns, Git, Automation, CI/CD, and Modular Design.
• The Clean Coder by Robert C. Martin
• Dependency Injection: Principles, Practices, and Patterns by Mark Seemann and Steven van Deursen
• Test Driven Development: By Example by Kent Beck
• Working Effectively with Legacy Code by Michael C. Feathers
• Design Patterns by Gamma, Johnson, Vlissides, Helm
• Clean Architecture by Robert C. Martin
• Pro Git by Scott Chacon

I have been doing iOS development for many years and I worked on many projects (including some open source). I have seen many codebases become hard to manage and just unpleasant to work with.

A while back, I became passionate about the concepts of Clean Code and Clean Architecture, so I tried to apply them to my projects.

I learned a lot from Robert Martin’s books and from the iOS Lead Essentials program.

Why Clean Code and Clean Architecture?

• IMO, it’s a fundamental part of building great software
• It’s agnostic of platform, language, technology
• Has a great impact on the lifetime and maintainability of systems

Here’s what I learned so far.

1. Hard to change codebases

How many times did you see codebases that with time are getting harder and harder to maintain / change?

They come with legacy code (code without tests), many flavours of code, many patterns, multiple languages (Swift, ObjC and more), they have huge files, unused code and resources, and most of the time, have some parts that nobody touches (because the guy that worked on that has left the team and nobody known how to work with that).

It’s definitely not profitable for a company to own such a codebase, so the ones that need to be maintained over years usually get to a point where they need to be rebuilt from scratch.

The problem with that (besides the obvious) is, without changing our principles, the new codebase will soon have the same issues as the old one.

2. What is Software

“Software” is a compound word = “soft” (changeable) + “ware” (product). The software must be changeable. It should be cheap and easy to make changes to the system.

3. Changeable software

How do you get changeable software? According to Robert Martin:

• you keep it clean
• you better have a really good suite of tests

4. Who is Robert C Martin

Robert Cecil Martin colloquially called “Uncle Bob” is an American software engineer, instructor, and best-selling author. He is most recognized for developing many software design principles and for being a founder of the influential Agile Manifesto.

He’s had a substantial role in stating the SOLID principles.

He’s authored several books, among which The Clean Coder, Clean Code, Clean Architecture.

Robert Martin had a continuous quest for what Clean code is and to establish industry standards for Software Development.

Many of Robert Martin’s teachings are applied for iOS in detail in the iOS Lead Essentials program.

5. What is clean code

Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent but rather is full of crisp abstractions and straightforward lines of control. – Grady Booch author of Object Oriented Analysis and Design with Applications

Clean code always looks like it was written by someone who cares. – Michael Feathers, author of Working Effectively with Legacy Code

You know you are working on clean code when each routine you read turns out to be pretty much what you expected … – Ward Cunningham, coauthor of the Manifesto For Agile Software Development

Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write. – Robert C. Martin

6. Principles of clean code

6a. The Boy Scouts rule

Leave the campground cleaner than you found it.

With every change (commit), we make the codebase just a bit better: fix a warning, remove a todo or an obsolete comment, add a test, improve a name, split a component that is getting too big, …

6b. KISS: Keep It Simple Stupid

A design principle originating from the U.S. Navy that goes back to 1960 already.

It states that most systems should be kept as simple as possible.

In my opinion, the art of designing code lies in simplicity - the simpler and easier to read / change code is, the better it is designed.

6c. DRY: Don’t Repeat Yourself

It states that every piece of code must have a single, unambiguous, authoritative representation within a system.

There’s a catch: duplication is usually the enemy, but similar (even identical code) doesn’t always mean duplication. We need to also look at the reasons to change.

Example: the representation of the API response (that changes when the API schema changes) and the business model that your core uses (that changes when the business requirements change). Even though they might start as duplicates, it’s good to have them separate so we can protect our business rules from API schema changes (otherwise on any change like that, we’ll have many changes to apply to other layers of the code).

// model object representing a feed item
struct FeedItem {
    let title: String
    let createdAt: Date
}

// network response representation of the feed item
struct RemoteFeedItem: Decodable {
    let title: String
    let created_at: String
}

6d. Keep things small

By things I mean all kinds of entities: functions, classes, interfaces (protocols), enums, structs, clojures, etc. Small pieces of code are easier to write, maintain and, most importantly, read and understand. There are guidelines used to increase readability about what those numbers should be: including max number of lines per function, per file, max characters per line and more.

Recommendations compiled by Robert Martin:

• 50 or less lines of code per file (on average)
  • keeping most files under 100 lines
• 30-40 or less characters per line
  • “It’s rude to make your readers scroll to the right”
• how small should a function be?
  • It should do one thing
  • like a few lines of code with 1 or a max of 2 levels of indentation
• how many arguments should a function have?
  • Ideally 0
  • 1 and 2 are good
  • from 3 arguments the function becomes a bit harder to understand and it might be doing too much

6e. Command-Query Separation

Side effects are changes the state of the system.

Functions with side effects (commands) usually come in pairs: open / close, malloc / free, init / dealloc, …

A command aka a function that returns void has side effects, otherwise it would do nothing. A query aka a function that returns a value should have no side effects.

Don’t create functions that return values and have side effects, they are very confusing.

6f. Prefer exceptions to error codes or optional returns

We prefer exceptions to error codes because they are more explicit.

When dealing with do / catch, we should not add more logic in a function than the do / catch block, so that function does one thing: handle errors.

Recommendation: don’t use nested do / catch.

See in the following example where the init throws instead of returning an optional CoreDataFeedStore (which would say nothing about why the API failed).

public final class CoreDataFeedStore {
    private static let modelName = "..."
    private static let model: NSManagedObjectModel? = ...
    private let container: NSPersistentContainer
    private let context: NSManagedObjectContext

    enum StoreError: Error {
        case modelNotFound
        case failedToLoadPersistentContainer(Error)
    }

    public init(storeURL: URL) throws {
        guard let model = CoreDataFeedStore.model else {
            throw StoreError.modelNotFound
        }
        
        do {
            container = try NSPersistentContainer.load(name: CoreDataFeedStore.modelName, model: model, url: storeURL)
            context = container.newBackgroundContext()
        } catch {
            throw StoreError.failedToLoadPersistentContainer(error)
        }
    }
}

6g. Proper use of access control modifiers

Many projects avoid using access control modifiers and just go with the default one (which currently in Swift is internal), but properly using access control has its advantages:

• first of all, they help us better express in code. When you see a type having private, internal and public properties / methods, it is very clear which ones were created to be used by outer layers and types and which are implementation details.
• testing our types through their public interface only (no use of @testable import) keeps the tests decoupled from the production code, allowing us to refactor the internal and private implementations without breaking the public contract
• it’s easier to spot entities that have too many responsibilities by looking at their public interface

7. Choosing good names

Names are everywhere (files, directories, programs, classes, variables, arguments, …). Because we do so much of it … we’d better do it well!

It is said that choosing good names is one of the most difficult tasks when writing code. Remember this is an iterative process and the names in your projects will evolve with time. Remember the Boy Scouts rule: leave the compound a cleaner then you found it.

The rules for naming recommended by Uncle Bob are based on Tim Ottinger’s Rules for Variable and Class Naming:

7a. Reveal your intent

• a name that requires a comment does not reveal it’s intent: var d: Int // elapsed time in days
• the name of a variable should tell us the significance of what that variable contains var elapsedTimeInDays: Int

7b. Use consistency when naming entities

• it’s confusing to see functions with get, retrieve, load, fetch, …

7c. Rule for variable names

“A variable name should be proportional to the size of the scope that contains it.”

7d. Short scope

• if the scope is very small, like 1 line, a single letter name is fine

  switch (lhs, rhs) {
    case (.failure(l), .failure(r)): return l == r // one line scope, using single letter names
  }
  

• this is because the scope is limited, so you don’t need the name to remind you of anything, the (name of the) function that generated the value should be enough
• inside an if statement, so maybe a couple of lines of code, the variable names inside should be very short

  if let data = cacheData {
    let cache = try decoder.decode(Cache.self, from: data) // scope limited to the if, using one word names
    completion(cache)
  }
  

• inside a while loop, the variables should be very short
• if you have a function (maybe 4 lines long), the variables inside should be pretty short, maybe a bit longer than the previous ones, maybe a word would be good for an argument
• instance variables that live inside a class have a longer scope (the scope of the class) so it should be long-ish: 2 words maybe

  struct FeedItem {
    let name: String
    let imageURL: URL
  }
  

• the arguments to a member function probably one word

  func save(_ feed: [FeedItem], completion: @escaping (SaveResult) -> Void)
  

7e. Large scope

• long scopes need long names
• global variables have a huge scope, so they should probably be very long

  // I don't think using global variables is a good practice, but as an exercise ...
  public let testsDefaultTimeoutInSeconds: Int = 1
  

7f. Rule for function names

“The name of a function is inversely proportional to the size of the scope that contains it.”

• as the scope gets larger, we want to shrink the name because it will be called a lot, from all over the place.
• also, if the function has a larger scope, it’s probably dealing with a high-level abstraction
• we would not want to call the open() function if the name was openFileAndThrowExceptionIfNotFound()
• as the scope decreases, the names start to get longer
• the instance methods of a class will probably have slightly bigger names
• private functions called by public functions will have even longer names
• private functions called by private functions will have even longer names
• this rule can apply recursively, as you go deeper the names will get longer
• as you keep extracting functions, those get smaller and more precise, that you need more words to specify

public func purgeAllData() { ... }

public final class DataManager: DataManagerInterface {
    public func loadObject<T: Codable>(from storageType: DataStorageType, with key: String, completion: @escaping (Result<T, Error>) -> Void) {
        switch storageType {
        case .secure:
            loadObjectFromKeychain(for: key, completion: completion)
        case let .disk(directory):
            loadObjectFromDisk(in: directory, with: key, completion: completion)
        case .memory:
            loadObjectFromMemory(with: key, completion: completion)
        case .userDefaults:
            loadObjectFromUserDefaults(with: key, completion: completion)
        }
    }
  
    private func loadObjectFromKeychain<T: Codable>(for key: String, completion: @escaping (Result<T, Error>) -> Void) {
        guard verifyKeychainStoreIsValid() else { return }
        keychainStorage.retrieve(forKey: key) { result in
            ...
        }
    }
  
    private func verifyKeychainStoreIsValid() -> Bool { ... }
}

7g. Rule for class names

“The name of a class is inversely proportional to the size of the scope that contains it.”

• classes at the global scope have one word names
• derived classes have multiple word names
• inner classes have multiple word names
• as the scope shrinks, the name grows

  protocol Store {}
  protocol FeedStore: Store {}
  final class CodableFeedStore: FeedStore {}
  final class InMemoryFeedStore: FeedStore {}
  

7h. Code Example

public List<int[]> getThem() {
    List<int[]> list1 = new ArrayList<int []>();
    for (int[] x : theList)
        if (x[0] == 4)
            list1.add(x);
    return list1;
}

• this code isn’t complicated
• but it’s not explicit. It reveals no intent
• the names do not explicitly reveal the context of the problem being solved

public List<int[]> getFlaggedCells() {
    List<int[]> flaggedCells = new ArrayList<int[]>();
    for (int[] cell : gameBoard)
        if (cell[STATUS_VALUE] == FLAGGED)
            flaggedCells.add(cell);
    return flaggedCells;
}

• only the names have changed and the meaning is far clearer
• now we know the list represents the game board and the function gets all the cells from a list that have the status flagged
• a good naming system will tell you more than the context of the function

7i. Disambiguate

• What’s the difference between the following?

  XYZControllerForEfficientHandlingOfStrings
  XYZControllerForEfficientStorageOfStrings
  

• Would you pick the right one from a code completion list?
• And watch out for symbols that look alike

  int a = 1;
  if (O == l)
    a = Ol;
  else
    l = 01;
  

7j. Avoid convenient mispellings

• klass vs aClass or theClass
• avoid situations where the code will break if a spelling error is fixed

7k. Number series

• the opposite of intentional naming
• provide no clue into the author’s intent

  public static void copyChars(char a1[], char a2[]) {
    for (int i = 0; i < a1.length; i++) {
        a2[i] = a1[i];
    }
  }
  

public static void copyChars(char source[], char destination[]) {
    for (int i = 0; i < source.length; i++) {
        destination[i] = source[i];
    }
}

7l. Noise words

• suffixes

  var product: Product
  var pd: ProductData
  var pi: ProductInfo
  

• data is completly redundant
• what is the difference between Product, ProductData and ProductInfo? the names don’t tell the difference
• prefixes

  var aProduct: Product
  var theProduct: Product
  

7m. Distinguish names meaningfully

• how to know which function to call

  func getActiveAccount() -> Account
  func getActiveAccounts() -> [Account]
  func getActiveAccountInfo() -> [Account]
  

7n. Make sure names are pronounceable

• Imagine you have the variable genymdhms (Generation date, year, month, day, hour, minute and second) and you need talk about this variable calling it “gen why emm dee aich emm ess”.
• that should be renamed to generationTimestamp

8. Comments

The purpose of comments is to explain code that cannot explain itself.

Nothing can be quite as helpful as a good comment. Nothing can be quite as obscure as a bad comment. Comments are not “pure good”.

The proper use of comments is: to compensate for our failure to express ourselves in code. Every use of a comment represents a failure. So don’t comment first. Try everything else, then comment as a last resort.

// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) > 0) && (employee.age > 65) {
    // ...
}

VS

if employee.isEligibleForFullBenefits() {
    // ...
}

Acceptable comments: copyrights, informative comments, warning of consequences, documentation comments in public APIs

8a. TODOs

TODOs are a nice IDE feature, but it’s recommended not to check them in, so fix them before, otherwise, they become DONTDOs

8b. Use explanatory code instead of comments

// does the module from the global list <mod>
// depend on the subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) {
    // ...
}

extract variables to explain things

ArrayList<Module> moduleDependees = smodule.getDependSubsystems();
Module ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) {
    // ...
}

8c. Commented out code

• few practices are as odious.
• don’t do this!

9. References

• iOS Lead Essentials program - Online program meticulously thought out for iOS developers who want to become world-class senior developers and be part of the highest-paid iOS devs in the world. Focuses on key concepts like Swift, TDD, BDD, DDD, Clean Architecture, Design Patterns, Git, Automation, CI/CD, and Modular Design.
• The Clean Coder by Robert C. Martin
• Clean Code by Robert C. Martin
• Test Driven Development: By Example by Kent Beck
• Working Effectively with Legacy Code by Michael C. Feathers
• Design Patterns by Gamma, Johnson, Vlissides, Helm
• Pro Git by Scott Chacon

What traits do professional developers possess, and how do they apply to the world of iOS and other Apple platforms? What standards do you use for iOS development compared to other platforms? I don’t know the full answer, but I know enough to start the conversation. I’d like to have a talk about Clean code, Clean architecture and modular design, SOLID principles, automated testing, TDD, CI and CD, and more.

About Robert C Martin

Robert Cecil Martin, colloquially called “Uncle Bob” is an American software engineer, instructor, and best-selling author. He is most recognised for developing many software design principles and for being a founder of the influential Agile Manifesto. Five of Martin’s principles have become known collectively as the SOLID principles. He is a proponent of software craftsmanship, agile software development, and test-driven development.

He has authored a series of books on Clean Code and Architecture.

What makes a professional developer

• Robert Martin is on a continuous quest to answer this question and establish industry standards
• see The Clean Coder
• what makes a professional in other fields: medicine, research, sports? They adhere to clear work guidelines, have rules, ethics and committees that verify their output

Professionalism is about taking responsibility

• Do no harm: don’t create bugs (almost impossible, but still…). Analogy: software systems are very complex and thus impossible to be bug-free. But the human body is also incredibly complex, but doctors still take the oath to do no harm
• QA should find nothing: delivering faulty code is just unprofessional
• You must know it works: automated tests
• Work ethic: your career is your responsibility (trainings, conferences, books, … and the time needed to learn)
• Know your field:
  • design patterns: GOF
  • design principles: SOLID
  • methods: XP, Scrum, Kanban, Waterfall, …
  • disciplines: TDD, OOD, Structured programming, CI, Pair programming
  • artifacts: UML, State Transition Diagrams and tables, flow charts, …
• Practice
• Collaboration
• Mentoring
• Know your domain
• Humility

Saying No and Saying Yes

• Professionals have the courage to say No to their managers, and they work hard to find creative ways to make Yes possible.
• Your manager is counting on you to defend your objectives as aggressively as they defend theirs. Both you and your manager need to get to the best possible outcome through negotiation.
• Professionals pursue and defend their objectives as aggressively as they can.
• Recognize lack of commitment words and phrases like “hope” and “Let’s see if we can get this done…”. A sincere commitment sounds like “I will do something… by this certain date…”
• Bring up blockers or red flags as soon as they come up — actively communicate.

Coding

• Coding is an intellectually challenging and exhausting activity.
• If you are tired, worried, or distracted, do not code. Your code will have bugs or a bad structure.
• Spend personal time before work trying to resolve or mitigate personal issues or demands, so you can focus your mental energy on being a productive problem solver at work.
• Be prepared to be interrupted and help someone — it’s the professional thing to do.
• Ask for and ask to give help - be a mentor.

Test-Driven Development

• Writing your tests first:
• Good tests function like good documentation.
• TDD is a discipline that enhances certainty, courage, defect reduction, documentation, and design.

Practice, Practice, Practice

• When performance matters, professionals practice.
• All professionals practice their art by engaging in skill-sharpening exercises.
• Doing anything quickly requires practice. It’s not always wise to go fast, but sometimes it is better to do it as fast as possible and is highly productive.
• Practice coding outside of work by doing katas.
• Open source: Take on some pro bono work by contributing to an open-source project.

Testing Strategies

Every professional development team needs a good testing strategy, and we can start by following the “Test Pyramid”: (image)

• Unit tests
• Component tests
• Integration tests
• System tests
• Manual tests

Time Management

• What strategies can you use to ensure that you don’t waste time?
• Meetings are both necessary and huge time wasters. You do not have to attend every meeting — be careful about which ones you decline and those you choose to attend.
• Use tools like the Pomodoro Technique.
• Evaluate the priority of each task, disregarding personal fears and desires, and execute those tasks in priority order.

Estimation

• Estimation is one of the simplest, yet most frightening activities that software professionals face.
• Know the difference between estimates and commitments.
• A commitment is something you must achieve. An estimate is a guess.
• Learn methods to get better estimates like PERT, Fingers in the Air and Planning Poker
• Always include error bars with your estimates so that the business understands the uncertainty.
• Don’t make commitments unless you know you can achieve them.

Stay Cool Under Pressure

• The professional developer is calm and decisive under pressure.
• Under pressure? Be sure to manage your commitments, follow disciplines, keep code clean, communicate, and ask for help.
• Don’t succumb to the temptation to create a mess to move quickly.

Collaborate

• Programming is all about working with people. It’s unprofessional to be a loner or a recluse on a team.
• Often, programmers have difficulty working closely with other programmers. That’s no excuse. Being a developer means working with people.
• Meet the needs - collaborate with your managers, business analysts, testers, and other team members to deeply understand the business goals.
• Pairing is a great way to share knowledge and the best way to review code.

Get Aligned with Your Teams

• Strive to have a “gelled” team.
• A gelled team is one that forms relationships, collaborates, and learns each other’s quirks and strengths.
• Teams are harder to build than projects. It’s better to form persistent teams that move together from one project to the next and can take on more than one project at a time.

Mentoring, Apprenticeship, and Craftsmanship

• The software development industry has gotten the idea that programmers are programmers, and that once you graduate you can code.
• Software apprenticeship is a three-step journey: starting from an apprentice and moving to journeyman before becoming a master.
• Be a craftsman - someone who works quickly, but without rushing, provides reasonable estimates and meets commitments. Know when to say No, but try hard to say Yes.
• If craftsmanship is your way of life, keep in mind that you cannot force other programmers to become craftsmen.

References

• iOS Lead Essentials program - Online program meticulously thought out for iOS developers who want to become world-class senior developers and be part of the highest-paid iOS devs in the world. Focuses on key concepts like Swift, TDD, BDD, DDD, Clean Architecture, Design Patterns, Git, Automation, CI/CD, and Modular Design.
• The Clean Coder by Robert C. Martin
• Clean Code by Robert C. Martin
• Dependency Injection: Principles, Practices, and Patterns by Mark Seemann and Steven van Deursen
• Test Driven Development: By Example by Kent Beck
• Working Effectively with Legacy Code by Michael C. Feathers
• Design Patterns by Gamma, Johnson, Vlissides, Helm
• Clean Architecture by Robert C. Martin
• Pro Git by Scott Chacon

To be clear, all the content belongs to Robert C. Martin, I merely summarized the content and updated the code examples for Swift.

Uncle Bob, your new CTO

In this lesson, Robert Martin guides us through an imaginative exercise where he is the new CTO at a tech company.

He focuses on raising awareness, given the need to increase the level of criteria in code production. Pointing to the lack of preparation in most programmers, as one of the main reasons for the inefficiency in software development today.

Robert Martin proposes a series of Expectations, through which he hopes to instill in the programmers, the knowledge and desire to prosper towards a way of programming based on ethics and responsibility.

1. We will not ship shit

People now regularly download and use betas. :) Beta software means code that probably doesn’t work well / as expected. It definitely has bugs. Betas should be used only in limited cases.

Robert Martin’s expectation is that we only ship code we know it works. It should have the highest quality level you can deliver. It should be clean, tested, well organized. Everybody expects that.

Example: when you buy a car, you expect it to work, to have been properly tested and you are going to complain bitterly if even the smallest thing doesn’t work.

2. We will always be ready

Agile = system is in a deployable / shippable state after every iteration / sprint. The system is ready, even if it doesn’t have enough features to deploy (that is a business decision). Ready to deploy = all the testing is done, all the documentation is done, the set of features is done. If you are not deployable at the end of the sprint, you are not doing Agile.

Iteration length: ideally 1 week, acceptable 2 weeks.

3. Stable Productivity

The longer the project goes, the slower you don’t get. You are able to produce features at the same rate even after a long time. Each added feature does not make the system harder and harder to maintain / change. The reason we slow down is because we make a mess. As the mess builds, we get slower.

Example from Robert Martin’s career: worked for a company where every estimate was 6+ months. The dev team’s cost of missing estimates was so high, they would not commit to anything under 6 months. Also, the system was highly coupled and you couldn’t even change a menu item’s name without affecting other areas.

4. Inexpensive Adaptability

The software must be changeable. It should be cheap and easy to make changes to the system.

Put otherwise, the size of the change should be proportional to the scope of the change.

He expects us not to respond to a small client change with: “Oh God, that destroys our entire architecture” :)

“Software” is a compound word = “soft” (changeable) + “ware” (product).

Software = changeable product. It was invented so our machines can be easily changeable. If it’s hard to change, you have just reinvented Hardware.

How do you get changeable software?

• you keep it clean
• you better have a really good suite of tests

5. Continuous Improvement

The code should be getting better with time (even if most of the time, the code rots.) The architecture of the system should be getting better with time.

6. Fearless Competence

If your reaction to bad code is “if I change it, I will have to own it”, then that code will end up rotting. You will change it from time to time, but with minimal changes to reduce the risk. You will not improve the system. No one will ever clean it.

How do you get fearless competence? With tests (you can run quickly and believe their outcome). You could make small improvements, run the tests and make sure the state is still green, then check it in, making the system a little better than before. It will be trivial (if the tests can be trusted).

Conquer the fear with tests: First write unit tests for the code you have written, then for code other people has wrote.

Fragile test problem is when the tests are so coupled with the production code than changing anything in the production makes a bunch of tests fail. This usually happen to beginners with unit testing. Tests must be designed, just like other components. Even outside tests, if a change in one component leads to many things breaking in others, that is just a bad design, if it’s tests or not.

Code coverage - there is no target number other than 100% that makes sense. Otherwise, you are ok with x% of the code just not working. Also don’t let managers see that number :) The team understands that this is just the number of lines of code being tested. If management adds this metric, developers start using less asserts and just increase coverage in a fake way.

7. We will not dump on QA

QA is not the tool we use to find bugs in our system. QA should find nothing. The responsibility of making sure the system works belongs to developers.

Manual QA is a less than ideal process, also are under a lot of pressure. QA belongs at the beginning of the process, not at the end.

8. Automation!

If a computer can do it, a computer should do it.

When under pressure (time), QA will not be able to run all the tests suite, so they will just execute some. That is really problematic.

9. We cover for each other

How do you make sure someone can cover for you when you are not available?

We can do this by pairing. Otherwise we end up with explicit responsibilities that only a person knows how to do.

Recommendation: a few times a week pair for an hour / half an hour.

Pairing is a better way to do code reviews.

10. Introduction to Honest Estimates

PERT estimate system - uses 3 numbers instead of one (best case, nominal - usual case, worst case)

Sources

• Clean Code - Uncle Bob / Lesson 3

To be clear, all the content belongs to Robert C. Martin, I merely summarised the content and updated the code examples for Swift.

Code sizing

Here are a few interesting insights from Robert Martin about the size of the code we write.

How many lines should there be in a source file

File size is not a function of project size, file size is a style you impose.

Aim for 50 or less lines of code per file (average), keeping most files under 100 lines of code.

Line lengths

Aim for lines up to 30-40 characters / line.

“It’s rude to make your readers scroll to the right”.

Names

Names are everywhere (files, directories, programs, classes, variables, arguments, …).

Because we do so much of it … we’d better do it well!

The rules for naming recommended by Uncle Bob are based on Tim Ottinger’s Rules for Variable and Class Naming.

Reveal your intent

var d: Int // elapsed time in days

• a name that requires a comment does not reveal it’s intent
• the name of a variable should tell us the significance of what that variable contains

var elapsedTimeInDays: Int

Rule for variable names

“A variable name should be proportional to the size of the scope that contains it.”

Short scope

• if the scope is very small, like 1 line, a single letter name is fine

switch (lhs, rhs) {
    case (.failure(l), .failure(r)): return l == r // one line scope, using single letter names
}

• this is because the scope is limited, so you don’t need the name to remind you of anything, the (name of the) function that generated the value should be enough
• inside an if statement, so maybe a couple of lines of code, the variable names inside should be very short

if let data = cacheData {
    let cache = try decoder.decode(Cache.self, from: data) // scope limited to the if, using one word names
    completion(cache)
}

• inside a while loop, the variables should be very short
• if you have a function (maybe 4 lines long), the variables inside should be pretty short, maybe a bit longer than the previous ones, maybe a word would be good for an argument
• instance variables that live inside a class have a longer scope (the scope of the class) so it should be long-ish: 2 words maybe

struct FeedItem {
    let name: String
    let imageURL: URL
}

• the arguments to a member function probably one word

func save(_ feed: [FeedItem], completion: @escaping (SaveResult) -> Void)

Large scope

• long scopes need long names
• global variables have a huge scope, so they should probably be very long

// I don't think using global variables is a good practice, but as an exercise ...
public let testsDefaultTimeoutInSeconds: Int = 1

Rule for function names

“The name of a function is inversely proportional to the size of the scope that contains it.”

• as the scope gets larger, we want to shrink the name because it will be called a lot, from all over the place.
• also, if the function has a larger scope, it’s probably dealing with a high-level abstraction
• we would not want to call the open() function if the name was openFileAndThrowExceptionIfNotFound()
• as the scope decreases, the names start to get longer
• the instance methods of a class will probably have slightly bigger names
• private functions called by public functions will have even longer names
• private functions called by private functions will have even longer names
• this rule can apply recursively, as you go deeper the names will get longer
• as you keep extracting functions, those get smaller and more precise, that you need more words to specify

public func purgeAllData() { ... }

public final class DataManager: DataManagerInterface {
    public func loadObject<T: Codable>(from storageType: DataStorageType, with key: String, completion: @escaping (Result<T, Error>) -> Void) {
        switch storageType {
        case .secure:
            loadObjectFromKeychain(for: key, completion: completion)
        case let .disk(directory):
            loadObjectFromDisk(in: directory, with: key, completion: completion)
        case .memory:
            loadObjectFromMemory(with: key, completion: completion)
        case .userDefaults:
            loadObjectFromUserDefaults(with: key, completion: completion)
        }
    }
  
    private func loadObjectFromKeychain<T: Codable>(for key: String, completion: @escaping (Result<T, Error>) -> Void) {
        guard verifyKeychainStoreIsValid() else { return }
        keychainStorage.retrieve(forKey: key) { result in
            ...
        }
    }
  
    private func verifyKeychainStoreIsValid() -> Bool { ... }
}

Rule for class names

“The name of a class is inversely proportional to the size of the scope that contains it.”

• classes at the global scope have one word names
• derived classes have multiple word names
• inner classes have multiple word names
• as the scope shrinks, the name grows

protocol Store {}
protocol FeedStore: Store {}
final class CodableFeedStore: FeedStore {}
final class InMemoryFeedStore: FeedStore {}

Code Example

public List<int[]> getThem() {
    List<int[]> list1 = new ArrayList<int []>();
    for (int[] x : theList)
        if (x[0] == 4)
            list1.add(x);
    return list1;
}

• this code isn’t complicated
• but it’s not explicit. It reveals no intent
• the names do not explicitly reveal the context of the problem being solved

public List<int[]> getFlaggedCells() {
    List<int[]> flaggedCells = new ArrayList<int[]>();
    for (int[] cell : gameBoard)
        if (cell[STATUS_VALUE] == FLAGGED)
            flaggedCells.add(cell);
    return flaggedCells;
}

• only the names have changed and the meaning is far clearer
• now we know the list represents the game board and the function gets all the cells from a list that have the status flagged
• a good naming system will tell you more than the context of the function

Disambiguate

• What’s the difference between the following?

XYZControllerForEfficientHandlingOfStrings
XYZControllerForEfficientStorageOfStrings

• Would you pick the right one from a code completion list?
• And watch out for symbols that look alike

int a = 1;
if (O == l)
    a = Ol;
else
    l = 01;

Avoid convenient mispellings

• klass vs aClass or theClass
• avoid situations where the code will break if a spelling error is fixed

Number series

• the opposite of intentional naming
• provide no clue into the author’s intent

public static void copyChars(char a1[], char a2[]) {
    for (int i = 0; i < a1.length; i++) {
        a2[i] = a1[i];
    }
}

public static void copyChars(char source[], char destination[]) {
    for (int i = 0; i < source.length; i++) {
        destination[i] = source[i];
    }
}

Noise words

• suffixes

var product: Product
var pd: ProductData
var pi: ProductInfo

• data is completly redundant
• what is the difference between Product, ProductData and ProductInfo? the names don’t tell the difference
• prefixes

var aProduct: Product
var theProduct: Product

Distinguish names meaningfully

• how to know which function to call

func getActiveAccount() -> Account
func getActiveAccounts() -> [Account]
func getActiveAccountInfo() -> [Account]

Make sure names are pronounceable

• Imagine you have the variable genymdhms (Generation date, year, month, day, hour, minute and second) and imagine a conversation where you need talk about this variable calling it “gen why emm dee aich emm ess”.
• that should be renamed to generationTimestamp

Sources

• Clean Code - Uncle Bob / Lesson 2

To be clear, all the content belongs to Robert C. Martin, I merely summarised the content and updated the code examples for Swift.

Comments

The purpose of comments is to explain code that cannot explain itself.

Schindler’s list

Nothing can be quite as helpful as a good comment. Nothing can be quite as obscure as a bad comment. Comments are not “pure good”.

Comments are a last resort

The proper use of comments is: to compensate for our failure to express ourselves in code. Every use of a comment represents a failure. So don’t comment first. Try everything else, then comment as a last resort.

Comments lie

• Not always
• Not intentionally
• But they silently rot
• They migrate

IDE’s usually display comments in a faded non-evident color, so they are easy to ignore. They get desynchronized from the code and can lead to more confusion. Delete comments when they are no longer necessary (code is clear enough).

Explain yourself in code

// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) > 0) && (employee.age > 65) {
    // ...
}

VS

if employee.isEligibleForFullBenefits() {
    // ...
}

Prefer using the name of variables and functions to explain the code.

Acceptable comments

Copyrights

//  Created by John McClane on 01/01/2020.
//  Copyright © 2020 Company. All rights reserved.

Informative comments

// Returns an instance of the Responder being tested
static func responderInstance() -> Responder

• this is useful, but it would be better if the function was renamed to responderBeingTested
• acceptable because it’s using the Singleton design pattern
• a better example of an informative comment is a comment explaining what a regular expression does (Java)

// format matched hh:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

• note: this comment actually lies, since the expression doesn’t match only the format in the comment

Explanation of intent

public int compareTo(Object o) {
    if (o instanceOf WikiPagePath) {
        // ...
    }
    return 1; // we are greater because we are the right type.
}

// This is our best attempt to get a race condition
// by creating large number of threads.
for (int i = 0; i < 1000; i++) {
    Thread thread = new Thread(widgetBuilderThread);
    try {
        thread.start();
    } catch (OutOfMemoryError e) {
        break;
    }
}

Warning of consequences

// Don't run unless you have some time to kill.
public void _testWithReallyBigFile() throws Exception {
    writeLinesToFile(10000000);
    response.setBody(testFile);
    response.readyToSend(this);
    String responseString = output.toString();
    assertSubString("Content-Length: 1000000000", responseString);
    assertTrue(bytesSent > 1000000000);
}

public static SimpleDateFormat makeLogFormat() {
    // SimpleDateFormat is not thread safe, so we need to create each instance independently
    return new SimpleDateFormat("dd/MMM/yyyy:HH:mm:ss Z");
}

TODO comments

• TODOs are a nice IDE feature, but it’s recommended not to check them in, so fix them before
• otherwise, they become DONTDOs

private SimpleResponse makeResponseWithXML(Document doc) throws Exception {
    // TODO MdM Should probably use a StreamedResponse
    ByteArrayOutputStream output = new ByteArrayOutputStream();
    // ...
}

Amplification

String listItemContent = match.group(3).trim();
// the trim is real important. It removes the starting
// spaces that could cause the item to be recognized
// as another list.

Javadocs in publis APIs

Javadocs is just an example, this applies to any documentation format that comes with public APIs (of a library / framework) and is used to generate a documentation set (like HTML).

Bad comments

Mumbling

public void loadProperties(String propertiesLocation) {
    try {
        String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
        FileInputStream propertiesStream = new FileInputStream(propertiesPath);
        loadedProperties.load(propertiesStream);
    } catch(IOException e) {
        // No properties files means all defaults are loaded
    }
}

• what does this mean?
• who loads the defaults?
• were they previously loaded or is that yet to come?
• was the author trying to remind himself to do it later?

Redundant comments

• it takes longer to read and understand the comment than it takes to read and understand the code

// Utility method that returns when this.closed is true. Throws an exception
// if the timeout is reached.
public synchronized void waitForClose(final long timeoutMillis) throws Exception {
    while (!closed && timeoutMillis > 0) {
        wait(100);
        timeoutMillis -= 100;
    }
    if(!closed) {
        throw new Exception("MockResponseSender could not be closed");
    }
}

• redundant comments (from Tomcat)

/** The child Containers belonging to this Container, keyed by name. */
protected HashMap children = new HashMap();

/** The processor delay for this component. */
protected int backgroundProcessorDelay = -1;

/** The lifecycle event support for this component. */
protected LifecycleSupport lifecycle = new LifecycleSupport(this);

...

Mandated comments

• it is just plain silly to have a rule that says that every function must have a javadoc,
• or every variable must have a comment
• comments like these clutter the code and propagate lies, confusion, and disorganization.

/**
 * @param title The title of the CD
 * @param author The author of the CD
 * @param tracks The number of tracks on the CD
 * @param durationInMinutes The duration of the CD in minutes
 */
public void addCD(String title,
                  String author,
                  int tracks,
                  int durationInMinutes) {
    // ...
}

Journal comments

/**
 * Changes (from 11-Oct-2001)
 * --------------------------
 * 11-Oct-2001 : Re-organised the class and moved it to new package com.jrefinery.date (DG);
 * 05-Nov-2001 : Added a getDescription() method, and eliminated NotableDate class (DG);
 * 12-Nov-2001 : IBD requires setDescription() method, now that NotableDate class is gone (DG); Changed getPreviousDayOfWeek(), getFollowingDayOfWeek() and getNearestDayOfWeek() to correct bugs (DG);
 * 05-Dec-2001 : Fixed bug in SpreadsheetDate class (DG);
 */

• this is why we have source code control systems

Noise comments

/**
 * Default constructor.
 */
protected AnnualDateRule() {
}

• these comments aren’t just redundant, they are noisy. So we learn to ignore them
• after a while our eyes don’t even see them.

Scary noise

/** The name. */
private String name;

/** The version. */
private String version;

/** The licenseName. */
private String licenseName;

/** The version. */
private String info;

• this was taken from a popular open-source framework.
• clearly noisily redundant.
• now read it again more carefully.

Use explanatory code, not comments

// does the module from the global list <mod>
// depend on the subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) {
    // ...
}

• extract variables to explain things

ArrayList<Module> moduleDependees = smodule.getDependSubsystems();
Module ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) {
    // ...
}

Position markers

// ------------------------------ Instance Variables

• these are usually pure clutter.
• banners are startling and obvious only if you don’y see them very often.

Closing Brace Comments

if ((result < 1) || (result > 12)) {
    for (int i = 0; i < monthNames.length; i++) {
        if (s.equals(shortMonthNames[i])) {
            result = i + 1;
            break;
        } // if
        if (s.equals(monthNames[i])) {
            result = i + 1;
            break;
        } // if
    } // for
} // if

• this is a noisy bad habit.
• shorten your functions instead.

Attributions and bylines

/* Added by Rick */

• Again, blame is what source code controls systems are for.

Commented out code

• few practices are as odious.
• don’t do this!

this.bytesPos = writeBytes(pngIdBytes, 0);
//hdrPos = bytePos;
writeHeader();
writeResolution();
//dataPos = bytePos;
...

HTML in comments

/**
* Task to run fit tests.
* This task runs fitnesse tests and publishes the results.
* <p/>
* <pre>
* Usage:
* &lt;taskdef name=&quot;execute-fitnesse-tests&quot;
* classname=&quot;fitnesse.ant.ExecuteFitnesseTestsTask&quot;
* classpathref=&quot;classpath&quot; /&gt;
* OR
* &lt;taskdef classpathref=&quot;classpath&quot;
* resource=&quot;tasks.properties&quot; /&gt;
* <p/>
* &lt;execute-fitnesse-tests
* suitepage=&quot;FitNesse.SuiteAcceptanceTests&quot;
* fitnesseport=&quot;8082&quot;
* resultsdir=&quot;${results.dir}&quot;
* resultshtmlpage=&quot;fit-results.html&quot;
* classpathref=&quot;classpath&quot; /&gt;
* </pre>
*/

Non-local information

/**
 * Port on which fitnesse would run. Defaults to <b>8082</b>.
 */
public void setFitnessePort(int fitnessePort) {
    this.fitnessePort = fitnessePort;
}

• if you must write a comment, then make sure it describes the code it appears near.
• where is the 8082 code?

Sources

• Clean Code - Uncle Bob / Lesson 2