carlos schults / blog

Building git in Go From Scratch - Part 2

Fri, 29 May 2026 00:00:00 +0000

Welcome back to my journey of building git from scratch in Go, in order to learn more about both. If you don’t know what I’m talking about, go read the first post.

It’s Been a While

I published the first entry for this log of sorts on March 9th. What have I been up to, and why it took me so long to continue the series?

The answer is what you probably already know: I’m a busy adult and don’t have much time. Also, there are other personal projects that demand my time.

Anyway, enough with the excuses. Let’s talk about what I’ve managed to implement since the last update.

Plumbing vs Porcelain Commands

Before I go into more detail about what I implemented, I’ll need to digress a little bit and talk about a distinction that exists regarding git commands.

When you think about git commands, what come to your mind are probably commands like git add, git init, git log, git status, and so on. And even that only if you actually use commands. Many people simply use GUIs for everything and never manage to learn not even the basic commands.

These are the so-called “porcelain” commands. They are the high-level commands, intended to be used by git’s end-users, like you and me.

There is another layer of commands, which people call “plumbing” commands. Plumbing commands are the low-level commands, which perform the nitty-gritty data manipulation that enables the high-level commands to do their work.

So, recently, I’ve been implementing some plumbing commands that act as the foundation for much of what git does. They are hash-object and cat-file.

Understanding `hash-object` And `cat-file`

I’m going to talk very briefly about what these commands do before I talk about my experience implementing them. hash-object is the command used to save some data as a blob (binary large object) inside a git repository. You give the command a piece of text, and it saves an object with that information, and gives you back a SHA1 hash.

The cat-file command does the opposite. You give it an object hash, and it returns you its contents (or size, or type, depending on how you call it).

Hashing Your First Object

Do you want to test it? Run the following command:

echo hi | git hash-object --stdin

After running this, you should see this exact hash as a result: 45b983be36b73c0788dc9cbcb76cbb80fc7bb057.

ℹ️ Info

If you’re on Linux or another Unix system, you probably got the result above. The same is true for Windows if you’re using Git Bash. But if you’re on Windows and using the command prompt or powershell, your result was probably different. That happens because of different line endings between the systems.

What happened here is that git calculated a hash for the “hi” string and returned it to you. We’re using the --stdin flag so you can pipe the content from the standard input.

However, that wasn’t saved anywhere. To actually write the data to disk, you need to use a different version of the command, and this time it needs to be inside a repository.

Saving an Object

Go to some place, create a new folder and a new repo inside it:

mkdir testing-commands
cd testing-commands
git init

That’s good. Now, you can do this:

echo hi | git hash-object -w --stdin

This is similar to how you used the command before, but notice the extra -w flag. That means write and it’s what makes git save the content to a file. You’ll still get the SHA1 hash as a response, same as before, but now you got a brand new blob git object saved somewhere. Wanna see it?

Go to the folder where this repository lives, then go inside the testing-commands folder. As in, using a GUI, not in the command line. Change whatever configurations you need so you can see hidden folders and files. You’ll see a .git folder:

Go inside this folder and you’ll see basically this structure:

├───hooks
├───info
├───objects   
└───refs
- config
- description
- HEAD

config, description and HEAD are files, and the others are folders. Go inside the objects folder. You’ll probably find an info and pack folders there, but ignore them.

What we’re really after here is a folder named with two characters. If you ran the commands above on Linux or using Git bash on Windows, it should be 45. Otherwise, it should be the first two characters of whatever hash you got back after running echo hi | git hash-object -w --stdin.

Go into that folder. Inside, you’ll find a file named after the remaining characters of the hash you got back. In my case, I see b983be36b73c0788dc9cbcb76cbb80fc7bb057.

That is your blob. That file is the object that git saved when you ran the hash-object command with the -w flag.

Reading Objects Back

Try opening the blob file using your text editor of choice. You’ll see that, yes, the file opens fine. But the contents are pure giberish. That’s because that’s a compressed, binary format. It isn’t plain text.

This is what git does, in sequence:

It creates a header, by concatenating the word “blob”, a space, and the size, in bytes of the contents. For instance, blob 2
Then it concatenates that with a null character
It then concatenates the actual content after that. In our example, “hi”.
It generates the SHA1 of the complete string.
If you’re not using the -w flag, git then returns the SHA1 and that’s it.
In case you are using the -w flag, it the compresses the complete string (header + null byte + contents)
It takes the two first characters of the SHA1 hash and creates a directory with that name, inside objects
Finally, it creates a file inside that folder, named with the remaining characters of the SHA1 hash, and writes to this file the contents, compressed using zlib.

In order to read this data back, you use the cat-file command, along with one of its flags. In order to just read the contents, you use cat-file -p, where the -p flag means “pretty print”:

git cat-file -p 45b983be36b73c0788dc9cbcb76cbb80fc7bb057

If you run the command above, you get “hi” back. You can also use the -t flag for the type of object, or -s to return its size in bytes:

git cat-file -t 45b983be36b73c0788dc9cbcb76cbb80fc7bb057
blob

git cat-file -s 45b983be36b73c0788dc9cbcb76cbb80fc7bb057
3

Enter Go-Gitter

Now that you understand what these two commands do, let’s talk about how I implemented them in go-gitter, starting with hash-object.

Implementing `hash-object`

My first step was implementing the most basic version of hash-object, without the -w flag. So, the command would be able to display the SHA1 hash for a given text, but not actually save it to disk yet.

As you can see from the commit, this is far from an example of clean code. The code mixes argument parsing and actual logic into the same file. At this point, I hadn’t even created functions for each command, though I ended up doing that later.

The part of the code that does the actual hashing turned out to be really simple, once I understood what the format was supposed to be:

size := len(data)
header := fmt.Sprintf("blob %s%c", strconv.Itoa(size), 0)
content := header + string(data)
hash := sha1.New()
hash.Write([]byte(content))
hashedData := hash.Sum(nil)
hashedString := hex.EncodeToString(hashedData)
fmt.Println(hashedString)

So, as you can see we create the header by concatenating the word “blob” plus a space with the size of the contents and then the null character, here represented by the integer zero. Then we hash everything, encode it as a string and print that.

It took me some googling to find out the necessary libraries and the syntax to do this in go, since my self-imposed rules say I can’t use LLMs for any code generation, but I ended up doing it fine.

In the next commit I added support for the -w flag. As you can see, at that point I created a function for the command.

There isn’t much difference, really. What I added was some primitive argument parsing to figure out whether I should write to disk.

Then, the actual code that does the writing:

if saveFile {
	// create the directory for the blob
	if err := os.Mkdir(".git/objects/"+folderName, os.ModePerm); err != nil {
		log.Fatal(err)
		os.Exit(1)
	}

	// compress the content using zlib and save the file
	var buffer bytes.Buffer
	w := zlib.NewWriter(&buffer)
	w.Write([]byte(content))
	w.Close()
	if err := os.WriteFile(".git/objects/"+folderName+"/"+fileName, buffer.Bytes(), 0666); err != nil {
		log.Fatal(err)
		os.Exit(1)
	}
}

It took me a bit of time to get this right. Mostly because at some point I was completely misunderstanding what git actually did. I thought I was supposed to compress and save the hash that I calculated earlier. Yes, I know, makes no sense, but what can I say?

Once I understood that, getting this to work was mainly a matter of figuring out the zlib compression part. Google and documentation did it for me, like in the old days.

Implementing `cat-file`

The cat-file command was easier to implement, because it’s essentially just the opposite. Based on a hash, find the corresponding file, uncompress it, and read its contents.

This time I created a dedicated function for the new command from the start, as shown in the first commit. This commit only implements the -p flag, though.

This is an abridged version of the code from the commit above, stripped of the function boilerplate and also the error handling:

folderName := h[0:2]
fileName := h[2:]
fullPath := filepath.Join(".git/objects", folderName, fileName)

var contents []byte
var err error
contents, err = os.ReadFile(fullPath)

r, err := zlib.NewReader(bytes.NewReader(contents))

buf := new(strings.Builder)
_, err = io.Copy(buf, r)

uncompressedContents := buf.String()
contentsWithoutHeader := strings.Split(uncompressedContents, "\x00")[1]
r.Close()
fmt.Println(contentsWithoutHeader)

The h variable is the SHA1 the command receives. From that, we get the directory and file name, which we then use to assemble the full path, read the contents of the file and then uncompres it.

Finally, I split the string by the null character and return the second part, which is whatever comes after the header.

The next commit after that implements the remaining flags. I won’t go line by line, since the important part is super simple:

parts := strings.Split(uncompressedContents, "\x00")
flag := arguments[2]
var result string

switch flag {
case "-p":
    result = parts[1]
case "-t":
    result = strings.Fields(parts[0])[0]
case "-s":
    result = strings.Fields(parts[0])[1]
}

Go programmers reading this: I suspect this code isn’t the most beautiful and idiomatic Go you’ve ever seen, and I promise you that once I learn more about the language, I will refactor this. The priority for me at the moment was getting it to work.

What I’ve Learned So Far

The goal of this project is to learn the Go language and also more about Git’s implementation. So, what did I learn about both by completing these two commands?

First, the Git side. I can say I was surprised about how simple is the way git saves objects. It is really just the type of the object, a space, the size, a null character to act as delimiter, and then the contents. I understood, at a high level, how git stored objects, but actually implementing it gave me an appreciation for how simple and elegant it all is.

And about the Go side? Generally speaking, I really like it. I appreciate how readable the language is. I think even someone with zero experience in Go could read this code and at least get the gist of it, as long as they are already a programmer.

I also like the fact that Go is opinionated. For instance, if you have an if statement, you have to use the curly braces. Otherwise, your won’t compile. So, this is one less thing for programmers to fight about and to have coding standard meeting about and to write linter rules about. It makes life simpler.

One aspect that I don’t like is the error handling. Having those if statements verifing err everywhere polutes the code. In C#/.NET, when there is an error that is something that should be absolutely impossible, I just let the exception bubble out until it reaches the top level exception handling middleware, where it gets logged and the user receives a message with the adequate level of detail.

Maybe there’s some idiomatic way to do something like that in Go as well, but right now I’m not aware. But other than that, I really like the language so far.

What’s Next?

For the next step I’ll implement another plumbing command called update-index. This is necessary so I can stage changes and eventually commit them.

If you want to play with go-gitter, install it like this:

go install github.com/carlosschults/go-gitter/ggt@latest

Then you can use the commands like this:

echo hi | gtt hash-object --stdin
ggt cat-file -p 45b983be36b73c0788dc9cbcb76cbb80fc7bb057

You should be able to hash something with real git and then reading it with go-gitter, and vice-versa.

Thanks for reading, and see you on the next update.

Your Commit Messages Suck. Let Me Show You How To Fix That

Tue, 31 Mar 2026 00:00:00 +0000

Your commit messages suck. They are, at best, useless. At worse, they are harmful and misleading. I don’t say this to be mean. Quite the opposite, I mean this in the most charitable way possible. I’m here to help.

If you know you’re the exception, you can stop reading. I’m serious, close this step and go watch some YouTube. There, I just gave you back some minutes, you’re welcome.

Still here? That’s great, recognizing you have a problem is the first step to get better. As I was saying, your commit messages are useless.

Don’t get offended. This is mostly not your fault. Chances are, nobody every taught you how to write good messages, or even why that’s important. And writing is freaking hard, let me tell you.

Good news is, you’ve finally got someone to help you. In this post, I will explain everything you need to know about terrible commit messages and, of course, how to write great ones instead.

Your commit Messages Suck Because…

Why is it that most commit messages are so bad? In my experience, the reasons amount to the reason I’ll talk about now. Keep in mind that there is nothing scientific or data-driven about any of these. They’re all based on my personal experience.

…You Only Care About Coding

If you’re like most developers, you only or mostly care about coding. This is where the fun lives, and everything else you see it as a waste of time. Also, I acknowledge that you’re probably under a lot of pressure to perform, to deliver as much value as quickly as possible. So, what you want the most is finish what you’re doing, merge your PR and then get another ticket off of Jira/Azure/Linear to start implementing.

What ends up happening is that anything that is not coding is treated like an afterthought and not given as much care. This includes testing, documenting, preparing a review of the implemented feature for the weekly retro and, of course, writing commit messages and PR descriptions.

…Sometimes You Don’t Understand What You’re Doing

Great commit messages and great documentation in general should focus on the why of things. What’s the motivation behind you making those changes? What’s the problem you’re trying to solve, why is it worth solving, in which way it helps your team and your company?

It may seem crazy that a programmer would start working on a task he or she doesn’t fully understand. But I know I have, and bet you have too. Of course, how are you supposed to explain the why behind a change when even you don’t fully grasp it?

…Writing Is Hard

As Phil Karlton once put, there are only two hard things in computer science, and naming things is one of them.

If you think about it, “naming things” is a form of writing. A subset of writing, if you will. So, yeah, writing commit messages is hard because writing, in general, is hard.

…Nobody Has Taught You

I think that developer education often fails to teach lots of important things that you actually need as a software engineer. True error handling is one of them.

Fair, they’ll teach you the mechanics of how a try-catch-finally work, but often they won’t teach you when to catch an exception, when not to catch it, when to throw an exception, when to log it or not, and so on.

And writing commit messages is one of those things.

…GitHub Taught You Bad Habits

Let’s get this out of the way: I use GitHub every day, and I love it. GitHub is the killer app for Git, and Git wouldn’t have gotten the same level of adoption without GitHub.

That being said, I do believe that the popularity of GitHub and pull requests caused people to care more about pull requests than about the individual commits. And it does make sense: pull requests support discussions that live on as a historical artifacts of that project, they support attachments, rich text and what have you.

So, it makes sense that some people don’t put a lot of effort writing good commit messages, claiming that they can write rich PR descriptions instead.

Of course what ends up happening frequently is that they don’t write PR descriptions either!

…Git’s `-m` Option Trained You Poorly

I think that most programmers don’t even know that commit messages can have a body with multiple lines. And the culprit here is the fact that most people teach the commitcommand like this:

git commit -m "Some message"

And not even mention that the -m flag is just a convenience for when you have a one-line message, which should be the exception rather than the norm.

…You Don’t Have Proper Commit Hygiene

Writing commit messages that aren’t trash is part of a broader thing that some people call “version control hygiene.”

This is exactly what it sounds like: don’t be a slob when writing code.

Sometimes you struggle when writing a commit message because you work in a messy way. If your changes are a hodgepodge of bug fixes, refactorings, dead code and half-baked implementation ideas, of course you’re going to have a problem writing a descriptive and useful commit message.

This is often caused by a lack of Git skills. If you don’t master tools like stashing, reseting, interactive rebasing and others, then you’re more likely to make a big mess out of your work.

Taxonomy of Bad Commit Messages

I have found that commit messages can be bad in a few number of categories. I’ll cover now some of them.

Almost Useless One-Liner

This is the one-line message that gives a high-level explanation of what the change was. I call it “almost” useless because at least the summary is accurate.

It then fails to add any more context. I’m left with questions like:

What was the problem that originated this change?
Why did the author consider this change to be the most optimal way of solving this issue?
Is there an issue or ticket associated with this work?

Some examples, with my comments:

Added new index to table # what index? what table? to what purpose?
Enable EF Core execution strategy# what is this strategy thing? why did you have to enable it?
Added Required attribute to model # Which model? Also, isn't this a breaking change that will affect current users?

Useless One-Liner

The useless one-liner is…well, like the almost useless one-liner, but completely useless.

The examples don’t merit more comments:

changes
ui
not working
more changes

I mean, by the time you’re writing “changes” as a commit message, you might as well just say “potatoes”. Or write a joke. It would be just as useless but at least it might have been funny.

Ticket System Reference Only

This is when people only add an id of issue/ticket/card from their issue system, and nothing more. Some examples:

JIRA-42
AZ-2234
#125

I think this category of commit messages manages to be both more useful but also more annoying then the previous ones. Yes, it’s more useful, since I can go always go to our ticketing system, look for the issue, and learn more about the work. Of course, nothing guarantees that the commit will only have changes related to the issue in question, but this is a conversation for another time.

This is also more annoying because it requires the reader to stop and go to another place to get context for that change. I don’t know about you, but I’d like to learn the reason behind a commit from the commit itself, just like ~~God~~Linus intended.

Besides the annoyance, there is a greater risk here: the possibility that, someday, your company will migrate from the current ticketing system and then you’ll be left without those descriptions. All companies I’ve worked for as a software developer have done at least one such migration, and I’m sure you probably have lived through at least one.

The Misleading One-Liner

Sometimes you have a message that says something seemingly harmless, like Add PrintHtmlOutput() method. And then it turns out the changes also add a breaking change to an endpoint or change something in the way the application interacts with the database.

You Will Write Great Commit Messages When You…

Now you understand why you write bad commit messages, and how they are bad. Ready to learn how to improve?

…Stop Writing One-Liners

One-liners are great when the scope of your change is small. If your commit only fixes a typo, then Fix typo is a valid commit message. But most often commits contain many more changes, and in those cases writing a one-liner is a missed opportunity to write a durable piece of documentation.

So, please, stop using the -m flag when commiting. Write a proper body with more detail for most of your messages.

…Lead With The “What”, Expand With The “Why” and “How”

So, now you know you’re supposed to write a summary and a body for most of your commit messages. What should be in each?

Simple: start with the summary, in which you describe what you did. Make it descriptive but concise.

Inside the body, describe what is the problem you’re trying to solve, or the reason that motivated the change. Then, explain how you solved it, but from a high-level perspective. Don’t add too much detail, because remember your reader can always see the diff.

If necessary, add more information, such as:

trade-offs involved in your decision
alternatives you considered but ultimately decided against
reference links for possibly unkown terms you used (for instance, a link to an Wikipedia article, or to Martin Fowler’s Catalog of Refactorings)
reference links for the solution you employed (for instance, a link to a Stack Overflow answer)

…Follow the 50/72 Rule

The 50/72 rule is the closest we have to a standard when it comes to commit messages. It was first proposed by Tim Pope and it goes like this:

Start with a summary, capitalized, and make it 50 characters long at the most
Add a blank line
Then you add a body, wrapping its lines at 72 chars at the most

These limits may seem arbitrary, but there are historical reasons they’ve been picked. To make a long story short, they play nicely with many different tools that work with commit messages.

Another important point is that you should write your summary in the imperative mood. That is, “Implement password hashing” instead of “Implemented password hashing”, for instance. At first, this might look weird, but this is the standard that Git itself uses. If you don’t believe, use git revert to revert a commit, and you’ll see that the generated commit’s message is in the imperative mood:

Revert "Add line of text"

This reverts commit 5ab08c5d3ee7bfdb334406d418d96f76d08962fe.

See? “Revert” instead of “Reverted.”

Additionally, and optionally, you can add a commit trailer. Commit trailers are metadata you can add to the bottom of your commit message, following the Name: value syntax. They’re used to add useful metadata, such as who signed-off on a change, who co-authored something with you, and also to associate your commit to an issue or ticket.

For instance, if you’re using GitHub issues, you can add a trailer like this:

Closes: #456

And it would automatically associate the commit to the issue and close it. There are other keywords you can use, such as Fixes, Resolves, Resolved, and so on. You can learn more about automatically closing GH issues here.

…Adopt Atomic Commits

The idea of atomic commits is simple: have a commit only contain changes that are logically related. This is the opposite of the lack of version control hygiene that I talked about earlier.

So, let’s say you’re currently working on a feature. Then your boss tells you to stop and fix a bug. You go and fix the bug, and then you have your changes from the start of your feature implementation.

Don’t commit everything together! Commit only the bug fix changes as a cohesive unit with a high-quality, descriptive message. Then you can go back to your feature and commit that.

Doing things like these require you master the tools of Git. You need to know how to stage changes and commit only those instead of everything. You need to know how to stash. Often, you’ll need to know how to commit things and then edit that history.

Those skills are worth having. Get them!

…Commit Often, Perfect Later

You don’t have to wait until you’re “done” to commit. Instead, you should commit all of the time. Work in small increments, and commit along the way.

That way, if you make mistakes and needs to throw some work away, you just revert a few minutes’ worth of work instead of hours. You also have those checkpoints you can go back to, should the power went off or something.

For instance, people who practice TDD (test-drive development) often commit every time they reach the green phase. In other words, every time they make the tests pass.

It’s also a good idea to leave all your commits clean. By that I mean, all of your commits, when applied, should leave your project in a state where it builds successfully and all tests pass. That makes it easier for you or someone else to use git bisect in the future to find where a bug was introduced.

But if you follow this tip, you might end up with many tiny little commits that don’t have good messages, or that don’t represent a cohesive set of changes. How to solve this?

The answer is: you edit your history to make it look beautiful. Editing your history is frowned upon, and with good reason, when it’s a branch other people already depend on. But if you’re working on your own isolated branch and no one depends on your changes, you can do whatever you want up to that point. So, commit early and often, then amend and rebase your way into a history that makes sense and has great commit messages.

Examples of Great Commit Messages

Now it’s finally time to show you some examples of valuable commit messages that incorporate everything we’ve been covering so far.

For instance, instead of:

Added Required attribute to model

Write:

Make PhoneNumber required on /reservations endpoint

The /reservations endpoint originally didn't require a phone number.
The reservations were being accepted but, as data flowed to downstream
systems, the lack of phone number was causing some processes to crash.

We are now adding the [Required] attribute to the PhoneNumber property
on the ReservationRequestModel. This is a breaking change, so that's
why, as part of this changes, we are versioning the endpoint as 2.0

Fixes: AB#456

See how it goes:

The message starts with a summary that describes what was done
The body starts with a problem statement, then explains how the current change solves it
Finally, we have a trailer to associate and close a ticket on our board

For the second example, let’s do something a bit more elaborate. Instead of Enable EF Core execution strategy, you can use:

Enable EF Core execution strategy for Azure SQL

After migrating to Azure SQL, save operations started failing
intermittently in production with transient connection errors.
Azure SQL occasionally drops connections during scaling events
and failovers, and Entity Framework does not retry failed
operations by default.

Enabled the built-in SQL Server execution strategy in EF Core,
which automatically retries failed operations using exponential
backoff when a transient error is detected.

An execution strategy is a configurable EF Core component that
intercepts database operations and decides whether to retry
them on failure. The SQL Server provider ships with a strategy
that knows which error codes Azure SQL considers transient.

[1]: https://learn.microsoft.com/en-us/ef/core/miscellaneous/connection-resiliency

Closes: #89

Do all messages need this kind of in-depth message? Or course not. For instance, Fix typo is a great commit message, if all you’re doing in that commit is fixing a typo. The same goes for Remove commented-out code, Remove blank lines, and so on. The length of your commit message needs to be directly proportional to the size/scope of your change.

AI Changes Everything. Or…Does It?

I know what you have been wondering all of this time. “But..but…but…what about AI?”

My honest take is that AI changes little, if anything at all, of what we’ve been discussing.

For starters, AI or not AI, the fundamentals remain the same:

Great commit messages should still focus more on the why instead of on the what and how.
The 50/72 is still a solid guideline to follow.
Using the imperative mood for summaries continues to be the standard for lots of tooling, including Git and GitHub themselves.
Great commit messages still carry immense value for future readers, which may include AI itself.

But AI is great at writing commit messages? Why should I bother?

When it comes to commit messages, AI is, in fact, great at one thing. And that is summarizing a collection of changes and writing a very well-written, grammatically correct, professional-sounding…detailed listing of all the changes.

Which is exactly what you shouldn’t be doing! Where AI fails is exactly the most important part, which, by now, you should be tired of reading: the why.

I’m not saying you shouldn’t use AI to help you in crafting commit messages. Of course you can. I use it a lot. This is an example of prompt I frequently use with Claude, with some variations:

Write a concise, well-crafted commit message for the diff I'm going to give you.
Make it more high-level, focusing on the why rather than listing all changes in great detail.
Follow these rules:
- Summary
	- Brief description of what was done
	- 50 chars at the most
	- Use imperative mood
	- Do not use conventional commits
- Body
	- Brief description of the "how", but focus more on the reason for the changes
	- Use prose rather than bullet points.
	- Use past tense
	- Lines no longer than 72 chars

And then I run git diff | clip and paste the results there with this prompt.

What I get back is always a message that is very well-written, much more detailed about describing changes than what I’d like, and that completely misses the point of why we’re doing the changes. Which is completely unsurprising, because how on Earth would it know if I haven’t told it?

Then, what I do is explain the reasons we did the change. And ask to try again, and make it more high level and include the explanation. Sometimes the second version I get is good enough, but often I need at least three until I’m satisfied.

Do you understand the pattern? This is a collaboration between the AI and I. We are working together to craft a message. I’m not 100% offloading it to the AI.

When I’m using Claude Code, those rules from above exist in the Claude.md file for the project. In this scenario, it tends to do much better understanding the “why”, because everything started with a prompt in which I explained the reason behind the change, and then we did a planning session before starting to implement the change.

But even then, the AI often still needs a lot of guidance until it’s able to write a commit message that really focus on the reasons behind the change and gives information at the right level of abstraction. Left to its own devices, AI produces well-written messages that are essentially a diff in prose.

Conclusion

By now, you’ve probably realized this was a fairly opinionated post. Some of the things covered here are very close to being a standard, such as the 50/72 rule and idea of writing the summaries using the imperative mood.

However, some of what I’ve discussed are personal preferences. For instance, I usually don’t use Conventional Commits. The reasons for that go beyond the scope of this post, but they exist. But they’re also fairly personal, so I won’t hold it against you if you like to use Conventional Commits.

The main takeway I want you to take from this post is: put some work into your commit messages. Don’t just write whatever; craft your messages. Work on them, hone them, until you can’t possibly improve them.

Yeah, that’s hard. It might be frustrating. It might feel a waste of time spending 10, 15, or even 20 minutes crafting a message that your favorite LLM could have knocked out in seconds.

But I guarantee you: years from now, when you’re investigating a critical production issue and then you’ve come across some great commit messages that offer valuable insights into why some changes were made…you’re going to be happy you did.

Thanks for reading.

Implementing git in Go From Scratch, For Fun and...Profit?

Mon, 09 Mar 2026 00:00:00 +0000

I’ve recently started working on my newest project: building git in Go, from scratch. What’s the point in that?, you might be wondering.

Well, it’s quite a useless project in the sense that, you know, git has existed for 20 years. (Thanks, Linus). My goal with this project is two-fold:

learn the Go language
strengthen my knowledge about git internals

Project Scope

I don’t intend to implement 100% of git. That would be simply too hard. What I’m going to do is to implement a small subset of git commands, only in their most basic variations for the most part. This is the current list of what I intend to implement:

git init
git add
git status
git commit
git log

This list isn’t static. I might decide to implement more commands, or fewer. It all depends whether I feel like I’ve learned enough. We’ll see how this goes.

Project Workflow (I really didn’t know what to call this section)

How will I go about all of this, in practice? I’m already going, since I’ve started about a week ago. So, the way I am going about this is basically going through that list of commands, implementing one by one, and documenting my learnings on this blog.

I’m not sure about the cadence of the blog posts yet, though. I feel like weekly updates are too much; since I only have about 30 to 50 minutes per day to work on this, I don’t want to lose too much time writing the updates themselves.

So I guess I will start by writing the posts whenever I feel I’ve accumulated enough interesting updates to share, then I’ll share them. I might later settle into a regular cadence, but don’t count on that.

About LLM Usage

I’ve imposed some rules on myself for this project. The most important one is that zero code will be written by AI/LLMs. It would defeat the purpose, since the goal of this is to actually learn the language.

That doesn’t mean I’m not using AI at all. I’m using Claude to help me plan the roadmap, so to speak. It’s been helping me decide the order of the commands that make more sense, what are the Go concepts that are required for me to build this and which ones I can skip, and so on.

For my actual Go learning, I’m using the Go documentation and good-old search. Like the old days.

Building git in Go: The First Update

So, what have I done so far? I’ve started this project on Monday, 2026-03-02. One week ago as the time of this writing. During the first three days, I’ve followed the Go Tour in order to remember the few things I knew about the language and to learn more of the fundamentals.

On Thursday, I finished the tour. I skimmed the lessons about generics very quickly and completely skipped the ones about concurrency. On this day, I created the repository and wrote a “Hello World.”

For some reason, I didn’t touch the project on Friday. Saturday was the day I actually implemented my first command, and the only one implemented so far: ggt init.

Oh yeah, by the way: my executable for this will be ggt, because the project itself is called go-gitter. Yes, it’s silly, but I like silly names, what can I do?

Implementing init was very easy and I’m sure it’s only getting harder from now on. Creating a git repository is surprisingly easy, and it’s something you can do manually, without using git itself at all. Doubt it? Ok, I’ll teach you.

Go somewhere in your computer and create a folder. Go inside this folder and create a new one called .git. Exactly like this.

Now, go inside .git and create a text file called HEAD. Just like this, without any extensions. Inside this file, put the following text, then save it:

ref: refs/heads/main

Next step: create two new folders, objects and refs. Inside objects, create yet two empty folders: info and pack. Inside refs, create heads and tags.

Now, using the terminal, go to the same level where the .git folder is and then run git status. You’ll see a result like this:

On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

Congrats! You’ve just created a git repo, manually. This is exactly what my Go code is doing.

Follow the Updates

The updates to this progress will be tracked by the go-gitter tag, so you can bookmark that page, if you want. I’ve already linked to the repository, but here it is again, in case you’ve missed: go-gitter.

Thanks for reading. See you on the next update.

What Are Breaking Changes?

Fri, 26 Sep 2025 00:00:00 +0000

Photo by Denis Oliveira on Unsplash

I’m starting a series of articles in which I’ll define some concepts or terms that are common in software development, and I’m starting with Breaking Changes. After all, why start with A like a normal person?

Ok, but…why write such a series?

Mainly because I want to create the resources I wish I had when I was starting out.

Back then, it used to drive me crazy when people would just casually say things like I was already familiar with them.

Mind you, I’m an ~~old~~ experienced developer, which means in my time I didn’t have an AI buddy to just ask those things. Yeah, Google was already a thing, how ~~old~~ experienced do you think I am? Jesus!

The problem is that often explanations you’d find by Googling weren’t that great. Often, Stack Overflow helped, but not always. Nowadays, of course, you can ask your favorite LLM side-kick to explain things to you, if you don’t mind the generic tone, depleted of any authentic human voice or anecdotes.

So, I’m writing these articles to help beginners out there understand a bit better some key software development concepts, one at a time, in a simple and hopefully engaging way, courtesy of yours truly.

Let’s begin?

What is a breaking change?

“Breaking change” means any change you make to your software that can cause the code of its users to break, after they upgrade. Breaking changes only make sense when you think about software that you create and somehow distribute for third-party users.

Think of things like:

APIs
libraries/packages
frameworks
CLI tools

Let’s see an example. While developing an application for your company, you extracted some common functionality as a library and decided to publish that as an open-source package hosted on https://www.nuget.org.

After a while, you publish a new version in which you change the name of one of the most important and used methods inside the package. Users upgrade to your newest version and now their code doesn’t compile, because it still refers to the method using the original name. That’s a breaking change!

ℹ️ NOTE

Important: for something to be a breaking change, it’s not required that 100% of the users break when they upgrade. In our example, it’s possible that not all users were actually using that specific method in their code which means their code wouldn’t have broken. But the change is still a breaking change, because the potential for breaking is there.

Examples of Breaking Changes

In practice, what types of changes are breaking changes?

I’d say the most common one, or at least what most people would think of as a breaking change, would be deleting or renaming things.

If you rename an API endpoint, a public class or method from your package, or a command from your CLI, code that uses those things will no longer work. And, for all practical effects, renaming is the same as deleting, because that old version no longer exists.

Where is the method that was here?

There are other types of breaking changes, though, so let’s review some of them.

New Required Parameters

If you add new parameters to a method, and they are required, then all existing code that calls the method will now fail to compile. The solution here would be to add new parameters as optional, or even create a new method.

Removed optional parameters or made them required

This is a logical continuation of the previous one. If you remove an optional parameter, code that calls that method padding the parameter will now break. On the other hand, if you make an optional parameter required, the opposite happens: now all of the places that don’t pass the parameter will break.

New Members Added To An Interface

Here I’m talking specifically about statically typed languages that have the concept of an interface in which you define behaviors that client classes need to implement.

Adding a new member to an interface is a breaking change because now all classes that implement it wouldn’t have implemented the new member.

Recently-ish, the C# team solved this problem in a way that sparked some controversy: adding the possibility of implementing methods on the interfaces themselves!

Changed the Type of a Method Parameter

If you change the type of a parameter from, say, string to int, you’re making sure that a lot of client code will break.

Changed return type of a method or function

Again, depending on the old and new types, this might not even break, but it’s still a breaking change in general.

Changed parameter order

This one is interesting because it might break in a different way than the others. For most of the examples I’ve been giving so far, “breaking” means that the code that consumes your code will fail to compile.

With this one, you can do it in such a way that the code still compiles, but it fails to work properly.

For instance, see this code:

public async Task<IReadOnlyList<Product>> GetProductsByCategory(int categoryId, int companyId)
{
// implementation
}

If you inverted the order between categoryId and companyId, the code would still compile but it wouldn’t work properly. It’d still be a breaking change, but one that fails in a subtler way.

Of course if the two parameters are of different types, then it would fail in the sense of failing to compile. And that’s why a lot of people argue that you shouldn’t use primitives for things like ids, but create your own tiny types for that.

Modified error handling behavior (throwing different exceptions)

If your method used to throw a certain type of exception and now it throws a different one, that’s a breaking change, because code that was written to catch that specific first exception won’t work for the new one, unless it inherits from the first one.

Made public methods or properties private

For the client this is, effectively, the same as deleting them, so it’s an obvious breaking change.

Added authentication requirements where none existed

Up until now, all of the examples were for libraries or packages. Now we’re going to see a few examples for web APIs. The first one has to do with authentication: if a given endpoint didn’t require authentication but now does, that’s a breaking change, because existing code that used to call that will now get a 401 Unauthorized error.

Added new required properties to a payload

That’s akin to adding new required properties to a public method, right? If your endpoint now expects a different payload than what it did before, existing code will break, likely getting a 400 Bad Request error.

Rename or delete an endpoint

This one is self explanatory.

What to do about breaking changes?

This should be obvious by now but let’s spell it out: breaking changes are A Bad Thing™. You should avoid them like the plague.

If you distribute any code of software publicly and there are people who depend on it, you won’t want to keep breaking their workflows frequently, or they’ll be mad at you, rightly so.

Sometimes there’s no use, though. You just need to do a breaking change, be it removing a method or class that has become obsolete, or changing the signature of a function.

When you have to do something like this, a few things are advised.

Gradually Deprecation

Adding a breaking change is something that you shouldn’t take lightly because it can dramatically disrupt the workflow of your users. Also, don’t do it all of a sudden, out of the blue, and in one step.

Before removing obsolete classes/methods/etc, first publicly announce you’re doing so, several versions in advance. Then, you mark that artifact as deprecated somehow, but still don’t remove it. For instance, in C# you can use the Obsolete attribute.

Then, after a few versions, you then finally do your breaking change.

Add Instructions to Your Release Notes

If you’re publishing software publicly for third-party use, you probably have some sort of release notes where you communicate what were the changes in this new version. Leverage that.

When it’s time to actually publish a version with a breaking change, use your release notes to describe, in detail, what the change is and how it will affect your users.

Usually, when a breaking change consists of retiring a method/class/endpoint, it comes accompanied by a new way of performing the same thing. After all, you wouldn’t be retiring the old way just because.

In those cases, also use your release notes to explain in detail how users can adapt their code to migrate from the old to the new way of doing the task.

Use Semantic Versioning

Finally, use Semantic Versioning and use the version number to communicate that this is a breaking change, by releasing a major version.

Semantic Versioning (or SemVer for short) is a standard for versioning in which you use a version number in this format: major.minor.patch.

When your new version only contains bug fixes, and they don’t add breaking changes, you increment the patch component.

For instance:

2.0.0 -> 2.0.1

If the version contains new functionality that doesn’t break compatibility, then you increment the minor component and reset the patch component:

2.0.1 -> 2.1.0

Now comes the most important part. When your version contains breaking changes, either cause by new functionality, bug fixes, or both, you increment the major number and reset the other two:

2.1.0 -> 3.0.0

That way, you clearly communicate to your users the presence or absence of breaking changes in your newest release.

Conclusion

In this post, I explained the concept of a breaking change, why it’s usually bad, and what to do about it. Quick recap:

Breaking changes are changes that break the code of your users, in the context of software that is distributed to third-party users.
Avoid adding breaking changes to your software, because they harm the experience of your clients.
Sometimes you can’t help but add a breaking change. In those cases, use gradual deprecation, communicate clearly what changed and how to adapt, and use semantic versioning.

I think that’s all. Thanks for reading, I hope this has been useful and I’ll see you again in the next installment of this series, in which I’ll probably go back to letter A, because I’m just weird like that.

How to Improve Developer Experience: 7 Things to Change

Tue, 08 Jul 2025 00:00:00 +0000

ℹ️ NOTE

I originally wrote this post for Nimbus. You can read the original at their site.

What’s Developer Experience? Why Should You Care?

In software development, we talk a lot about user experience, and rightly so. Since it’s the end user who benefits directly from the software we write, it makes sense that they’re front and center in all our efforts. But recently, another term has started to gain traction in the context of improving software quality: developer experience.

That’s what this post is all about—developer experience. We’ll open by briefly explaining what developer experience is and why all software organizations should care about it. From there, we’ll jump into the practical bit by walking you through a list of suggestions you can adopt right away to improve the developer experience for your team or company.

Here’s my definition of developer experience: how comfortable, straightforward, and enjoyable the experience of software development is for a given team or organization.

Why is developer experience so important? Why have people started talking about it so much recently?

It’s not rocket science. Software is tremendously valuable, thus the people who create software are tremendously valuable as well. It’s in the interest of any company that creates software to keep its developers happy and productive, especially in a hot market where developers are offered opportunities left and right.

If you improve the developer experience at your company, you’re more likely to attract great developers and keep the ones you already have. Productivity is likely to go up, and so is the quality of output.

Developer Experience: Improve It With These 7 Tips

Without further ado, let’s see seven practical suggestions you can adopt today to improve the developer experience at your organization.

1. Minimize Interruptions

Generally speaking, software developers hate interruptions. Not because we’re prima donnas who can’t be bothered with meetings or activities that can be described as “social” (though some of us certainly are.)

The problem with interruption is that software development is an activity that requires long stretches of intense focus. As any professional whose craft demands such a level of focus will say, achieving that state takes time and effort. However, losing it is easy: all it takes is Bob from accounting or your manager to drop by your cubicle or ping you on Slack to make that focus disappear into thin air.

To improve developer experience, minimize interruptions. In more practical terms, do the following:

Use asynchronous communication as much as possible. Try to use an internal newsletter, wiki articles, and e-mail updates instead of meetings and calls.
Adopt a meeting-free day. Pick a day of the week, or at least half a day, in which everyone’s calendar is blocked and can’t be booked. That will give everyone the chance to have dedicated time for deep concentration.
Optimize the time and duration of meetings. Meetings are unavoidable sometimes. When that’s the case, pick a time and duration that makes it easy for people to focus. For instance, if your company’s work hours end at 6:00 p.m., don’t schedule a meeting that ends at 5:30. Those final thirty minutes will most likely be lost since they’re not sufficient for developers to achieve the deep focus they need.

2. Invest in Technical Excellence

Most developers want to know that their work matters. They want to know that they’re working for a team that creates software to the highest standards using the best possible practices available and delighting users with great features delivered at a fast pace.

Thus, investing in technical excellence is a great way to improve the experience of developers. The list of what you can do includes the following:

Adopt automated testing and, optionally, test-driven development (TDD).
Use continuous integration (CI) and continuous delivery and deployment (CD).
Have a code review process or, alternatively, pair programming.
Use static analyzers and linters to detect common issues in the code.
Gather and track quality metrics.

These are just a few suggestions about what you can do to foster a culture of technical excellence in which developers feel pride in their work and feel like their work has a purpose.

3. Give Developers Autonomy

Autonomy is a big driver of productivity and happiness at work. In order to feel fulfilled, people need to have at least some degree of autonomy over the way they do their jobs.

Generally speaking, developers should be awarded a high degree of autonomy over how they do their work. Allow teams to decide the following:

Which branching workflow best suit their needs
Whether they estimate using points, T-shirts sizes, hours, or something else entirely
How strictly they want to adhere to the ceremonies of their preferred flavor of agile (for instance, whether or not to have a daily scrum)

On an individual level, allow developers to choose whether they want to work remotely, at the office, or in a hybrid way. Give the contributor flexibility to assemble a benefits package that makes sense for them (some people have children, others do not, so benefits that cater only to people who are married with kids are bound to alienate a sizable part of your workforce.)

4. Remove the Friction When Creating Development Environments

One thing that virtually every developer hates is a manual, tedious, and error-prone process when creating a new development environment. These processes cause developers to take a long time until they’re able to contribute code to the team. Worst of all, the processes are often not easily reproducible, which means differences between environments can be introduced.

As a consequence, the development environment drifts away from staging and production, making bugs more likely and creating the infamous “it works on my machine” excuse.

To improve developer experience, invest in ways to facilitate the creation of consistent and reproducible environments. Container solutions such as Docker are a great way to achieve that. Alternatively, you can leverage solutions that offer the creation of development environments in the cloud.

5. Invest in Developer Education

Developers also have a great experience when they feel like they master the tools of their trade. The feeling of being in control is simply exhilarating. It doesn’t only lead to higher quality output, but it’s also more enjoyable.

So, a sure way to improve developer experience is to invest in their education. There are several ways to do that:

Offer developers a monthly or annual stipend that they can freely use to invest in courses, books, or certifications.
Give developers time (as in, paid company time) during which they can study and practice
Offer company-paid learning resources such as a company library or services like Udemy or Pluralsight

6. Don’t Be Cheap When It Comes to Tools

If you want your developers to do great work, you must give them the tools to do so. If your developers can’t deliver great work due to a slow computer or the lack of a software license, that’s on you.

Your engineers should have great hardware, such as a company-provided laptop, monitor, keyboard, and so on (and even office supplements like a great chair).

You should also provide the necessary software. That includes IDE licenses, subscriptions to services, plugins, and what have you. No matter what your developers need in order to perform their work, the company should, within reason, provide it.

7. Listen to Developers’ Feedback (and Act Upon It)

Last but not least, here’s the final item on our list: listen to your developers!

Here’s the thing: software developers are usually smart people who care about what they do. Chances are they have pretty good ideas about how to improve not only their own experience but that of their teams and organizations as a whole.

Listen to your developers. When it makes sense, put their suggestions into practice. Besides the benefit created by the suggestion itself, this will have the additional benefit of improving the team’s morale. Your developers will feel valued and like an essential part of the team. Which, of course, they are.

Improve Developer Experience, Improve Your Company

If your organization is a tech organization, then software developers are arguably your most precious assets. So, improving developer experience, besides being a decent, human thing to do, is also a great investment. It’s in your best interest to keep your developers happy and productive, and as you’ve seen in this post, this is something you can achieve relatively easily.

The suggestions in this post are simply suggestions. Your mileage can vary (for instance, if you work in a highly regulated industry, giving developers a high degree of autonomy may not apply.) As always, use your judgment. Consider the list in this post as a starting point. Tweak it as needed, trim it, and add to it. What matters is that you improve the developer experience at your company for the sake of your developers, your end users, and the company as a whole.

Thanks for reading!

Git Switch Branch: Everything You Need to Know

Tue, 15 Apr 2025 00:00:00 +0000

ℹ️ NOTE

I originally wrote this post for Cloudbees. You can read the original at their site.

Repositories in Git work in a fundamentally different way from most other tools. One of the most glaring examples of said differences is branching. In most other VCS tools, branching is this elaborate ceremony. They make a huge deal out of it, and developers just give up, preferring workflows that don’t rely on many branches.

In Git, the opposite is often true: branching is so cheap that most people do it a lot. People often get confused when trying to manage their branches. This post attempts to clear up some of that confusion by offering a guide on how to successfully git switch branch in an easy and safe way. Before we get there, though, we start with some basics, explaining what branches actually are in Git, how they work and how you create them.

Before wrapping up, we share a bonus tip, covering how to check out remote branches. Let’s get started!

How Do Git Branches Work?

How do branches work in Git? The first thing you need to know is that a repository in Git is made up of objects and references. The main types of objects in a Git repository are commits. References point to other references or to objects. The main types of references are—you’ve guessed it—branches.

Objects in Git are immutable. You can’t change a commit in any way or move its position in history. There are commands that appear to change things, but they actually create new commits. References, on the other hand, change a lot. For instance, when you create a new commit, the current branch reference is updated to point to it.

When you create a new branch, all that happens is that a new reference is created pointing to a commit. That’s why it’s so cheap and fast to create branches in Git. Speaking of which…

How Do I Create a New Branch?

We already have a whole post explaining how you can create a branch in Git, covering the four mains ways to do that.

Here, we’ll just cover the easiest way to create a branch in Git, which is simply using the branch command from the current branch. Let’s see an example:

mkdir git-switch-demo
cd git-switch-demo
git init
touch file1.txt
git add .
git commit -m "Create first file"
touch file2.txt
git add .
git commit -m "Create second file"
touch file3.txt
git add .
git commit -m "Create third file"

In the example above, we’ve created a new repository and added three commits to it, creating a new file per commit. Here’s a visual representation of the current state of our repository:

To create a new branch from the current point, we just have to run:

git branch example

We’ve created a branch but haven’t switched to it yet. This is how our repo looks like now:

What if we added a new commit while still in the master branch? Would that impact the example branch? The answer is no. Execute the following commands:

echo "Another file" > file4.txt
git add .
git commit -m "Create fourth file"

In the next section, we’ll show how you can git switch branch, and then you’ll be able to see for yourself how that new branch doesn’t contain the fourth commit. For now, take a look at the visual representation of the current state of our repo:

How Do You Switch Branches?

For most of Git’s history, the checkout command was used for that. While you can still use it, version 2.23 of Git added the switch command (as well as the restore command) in an attempt to have more specific commands for some of the many tasks the checkout command is used for.

How Do I Use Git Checkout?

The older, more well-know way of switching branches in Git is by using the checkout command. Following our example, if we wanted to change to the “example” branch, we’d just have to run:

git checkout example

After executing the command, you should see a message saying that you’ve successfully switched to the example branch:

Now you’re in the new branch, that means you can add how many commits you want, knowing that the master branch won’t be impacted. The checkout command, followed by a branch name, updates the working tree and the index, and it updates the HEAD reference, pointing it to the branch you’ve just checked out. What if you had uncommitted changes at the moment of switching? Those would be kept to allow you to commit them to the new branch.

Git allows you to use the checkout command in different ways. For instance, an incredibly common scenario is to create a branch and immediately switch to it. In fact, I’d argue that creating a branch and not changing to it on the spot is the exception rather than the rule. So, Git offers us a shortcut. Instead of creating a branch and then checking it out, you can do it in one single step using the checkout command with the -b parameter.

So, doing this:

git checkout -b new

is equivalent to this:

git branch new
git checkout new

Checkout doesn’t work only with branches, though. You can also checkout commits directly. Why would you want to do so?

Well, taking a look at how the project was some amount of time ago is often useful, particularly for testing purposes. But there’s more. Checking out a commit puts your repository in a state called “detached HEAD” which allows you to create experimental changes, adding commits that you can then choose to keep or throw away.

What Is Git Switch?

For the most part of Git’s lifetime, the checkout command was the only one you’d use for switching branches. The problem is that this command also does other things, which can lead to confusion, especially among new users.

The 2.23.0 version of Git solves this by adding two new commands: switch and restore. The restore command isn’t relevant for us today. The switch command, on the other hand, is a new way to switch to branches.

The manual page for the command lists all of its many options. On its most basic form, you use it the same way as git checkout, only swapping the command’s name:

git switch example

If you want to go back to the previous branch, you can use a shortcut instead of its full name:

git switch -

What if you want to create a new branch and immediately switch to it? With checkout, we could use this shortcut:

git checkout -b <branch-name>

The new command also offers a shortcut, but in this case, we use the letter “C”:

git switch -c <branch-name>

Is using the new command worth it? Well, I’ll probably keep using git checkout, as long as they don’t change it, mainly because of muscle memory. But when teaching Git to beginners? Then I’ll definitely use the switch command. It has a name that’s more closely related to the task it does and, therefore, it’s more memorable.

How Do I Switch to a Remote Branch?

Before wrapping up, we share a final tip: how to switch to remote branches?

For this example, we’re going to use an open-source project called Noda Time, which is an alternative date and time API for .NET. Start by cloning the repository:

git clone https://github.com/nodatime/nodatime.git

If everything worked fine, you should have a “nodatime” folder now. Enter the folder and run the following command:

git branch -a

The branch command lists the branches in your repository. The “-a” option means you want to see all branches, not only local ones. The result should look like this:

As you can see, we have only one local branch, which is the master branch. You can see, in red, all of the remote branches. So, let’s say you want to check out the branch called “slow-test.” How would you go about that?

Well, technically speaking, Git doesn’t allow you to work on other people’s branches. And that’s what remote branches are. What you actually do is to create a local “copy” of someone else’s branch to work on. So, let’s see how to do it.

When you create a branch, you can pass a commit or branch name as a parameter. So, in order to create a local branch from the remote “slow-test” branch, I’d just have to do:

git branch slow-test origin/slow-test

In the example, I’m using “slow-test” as the name for my local branch, but I could’ve really used any other valid name.

Alternatively, I could’ve used the checkout command with the -b option or the switch command with the -c option. So, the two following lines are equivalent to the line above:

git checkout -b slow-test origin/slow-test
git switch -c slow-test origin/slow-test

Finally, there’s an even easier way. I could’ve just used:

git checkout slow-test

and the result would have been the same. That works because when you try to check out a branch and Git doesn’t find a branch with that name, it tries to match it with a remote branch from one of your remotes. If it can successfully match it, things just work.

Git Branches: Use in Moderation

In this post, we’ve shown you how to switch branches in Git. But we went further than that: we’ve explained what branches are and how they work. Hopefully, by now, you’re more comfortable creating and using branches in Git.

Before we go, a final caveat: just because you can do something, it doesn’t mean you should. Sometimes people get so carried away with the ease of branching in Git they end up using workflows that rely on a number of long-lived branches, which makes their development process way too complex and error-prone and delays integration.

Thanks for reading, and until next time.

Type-Safe C#: How GenAI Makes Tiny-Types Worth It

Tue, 10 Dec 2024 00:00:00 +0000

It’s weird how our memory works, right? I can’t quite remember what I had for dinner two nights ago, or the reason why I failed to attend the gym some days last week. But I do remember vividly a specific bug that I fixed in my first programming job after graduating from college.

There was this method that wasn’t working properly, and its signature was something like this:

void ProcessOrder(int orderId, int customerId)

I’ve reviewed its code and couldn’t find anything wrong with it. But when I started debugging, I realized that the calling site was passing the arguments in the wrong order—that is, customerId first and then orderId.

Mistakes like this are easy to make and hard to spot even in code review. Even testing might let it slip, since you might have the misfortune of supplying values that accidentally make the code work without blowing everything up.

As it turns out, there’s a great way to prevent issues like the one I’ve just described. The problem? Most developers would think it’s too much work to bother.

Tiny Types: The Greatest Software Design Technique That Nobody Uses

I know, I know. I’ll be the first one to admit this title is overblown. “An Interesting Software Design Technique That Many People Don’t Use” just doesn’t pack the same punch, I’m sorry.

So, what’s this “tiny types” thing about? It’s a radical solution to the primitive obsession code smell. Essentially, instead of using primitive types for domain concepts—for instance, using an int to represent a unique identifier—you wrap them all using an extremely simple value object.

Using tiny types, we could rewrite the method signature from before like this:

void ProcessOrder(OrderId orderId, CustomerId customerId)

Implementing a Tiny Type

What would the OrderId type look like?

For starters, since OrderId is supposed to wrap an int, it should get an int as parameter and store it somewhere. Let’s see:

public class OrderId
{
    private readonly int _value;
    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(value),
                "Value must be a positive integer!");
        }
        _value = value;
    }
}

I think the above is a good start, wouldn’t you agree? We get an int as parameter, validate and throw an exception in case of zero or negative values, and then assign it to a private readonly field, which is fitting, since OrderId, as a value object, must be immutable.

Do you know what else value objects—and, by consequence, tiny types—need? Structural equality. That is, when comparing them, we should only consider their values, not whether their references point to the same object.

So, let’s start by overriding Equals:

public override bool Equals(object? obj)
{
    var other = obj as OrderId;
    if (other == null)
    {
        return false;
    }
    return other._value == _value;
}

(For a more modern C# style, we could’ve used pattern matching, but I think the approach above is clearer.)

I get now a compiler warning because my type overrides Equals but not GetHashCode, so let’s fix that:

public override int GetHashCode()
{
    return _value.GetHashCode();
}

Since OrderId is a simple type representing unique, immutable values, it should really be a struct instead of a class, according to Microsoft’s Type Design Guidelines:

Structs are the general case of value types and should be reserved for small, simple types, similar to language primitives.

But the design guidelines also say that all structs should implement the IEquatable<T> interface, so let’s do that. While we’re at it, let’s also implement IComparable<T> and overload comparison operators:

public struct OrderId : IEquatable<OrderId>, IComparable<OrderId>
{
    private readonly int _value;
    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(value),
                "Value must be a positive integer!");
        }
        _value = value;
    }

    public override bool Equals(object? obj)
    {
        if (obj is OrderId other)
        {
            return _value == other._value;
        }
        return false;
    }

    public bool Equals(OrderId other) => _value == other._value;

    public override int GetHashCode()
    {
        return _value.GetHashCode();
    }

    public int CompareTo(OrderId other) => _value.CompareTo(other._value);

    public static bool operator ==(OrderId left, OrderId right) => left.Equals(right);
    public static bool operator !=(OrderId left, OrderId right) => !(left == right);
    public static bool operator <(OrderId left, OrderId right) => left.CompareTo(right) < 0;
    public static bool operator >(OrderId left, OrderId right) => left.CompareTo(right) > 0;
    public static bool operator <=(OrderId left, OrderId right) => left.CompareTo(right) <= 0;
    public static bool operator >=(OrderId left, OrderId right) => left.CompareTo(right) >= 0;
    
    public override string ToString() => _value.ToString();
}

There are more things we could add, such as implicit/explicit conversions, but our type is already functional as it is. For those using modern C#, we could achieve the same with a more concise syntax:

public readonly record struct OrderId : IComparable<OrderId>
{
    private readonly int _value;

    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(value),
                "Value must be a positive integer!");
        }
        _value = value;
    }

    public int CompareTo(OrderId other) => _value.CompareTo(other._value);

    public static bool operator <(OrderId left, OrderId right) => left.CompareTo(right) < 0;
    public static bool operator >(OrderId left, OrderId right) => left.CompareTo(right) > 0;
    public static bool operator <=(OrderId left, OrderId right) => left.CompareTo(right) <= 0;
    public static bool operator >=(OrderId left, OrderId right) => left.CompareTo(right) >= 0;
    
    public override string ToString() => _value.ToString();
}

Tiny Types Are Too Expensive

My tiny OrderId type there takes 42 lines on my Visual Studio. Yes, there’s some stylistic choices involved—for one, I do not like when lines are over 80 characters of length—but even so, it’s quite some work.

The more concise version, which leverages the record feature of modern C#, is shorter, but still requires a reasonable amount of code.

Now imagine doing this for all ids in your application! And not only ids, of course. Imagine doing this for more types that required more complex validation/parsing:

Zip codes
License plates
Telephone numbers.

And so on.

That’s the main reason why developers who know this technique don’t use it. Even when they like the idea and understand how it could be beneficial, they think doing all of that isn’t worth the trouble.

LLMs To The Rescue

It’s been two years since OpenAI introduced ChatGPT to the world, and I’ve been experimenting with LLMs since then. My current take on them is that their value proposition for experienced devs is two-fold:

They act as a replacement for Google when learning something new
They act as a code generator for mundane stuff I’d rather not do.

A few months ago, I’ve become a paid subscriber of Claude. I’ve been using it mainly as an aid in a hobby project I’m working on, and I must say I’m very satisfied with the results I get, since Claude is much better than ChatGPT for programming tasks.

I went to Claude with the following prompt:

Generate a type called OrderId. It should be a wrapper over an int. Don’t allow zero or negative values. Implement equality, hash code, overload comparison and equality operators.

Don’t add explicit or implicit conversions.

And this is the result I’ve got:

public readonly struct OrderId : IEquatable<OrderId>, IComparable<OrderId>
{
    private readonly int value;

    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentException("Order ID must be greater than zero", nameof(value));
        }
        this.value = value;
    }

    public override bool Equals(object? obj)
    {
        return obj is OrderId other && Equals(other);
    }

    public bool Equals(OrderId other)
    {
        return value == other.value;
    }

    public override int GetHashCode()
    {
        return value.GetHashCode();
    }

    public int CompareTo(OrderId other)
    {
        return value.CompareTo(other.value);
    }

    public static bool operator ==(OrderId left, OrderId right)
    {
        return left.Equals(right);
    }

    public static bool operator !=(OrderId left, OrderId right)
    {
        return !(left == right);
    }

    public static bool operator <(OrderId left, OrderId right)
    {
        return left.CompareTo(right) < 0;
    }

    public static bool operator <=(OrderId left, OrderId right)
    {
        return left.CompareTo(right) <= 0;
    }

    public static bool operator >(OrderId left, OrderId right)
    {
        return left.CompareTo(right) > 0;
    }

    public static bool operator >=(OrderId left, OrderId right)
    {
        return left.CompareTo(right) >= 0;
    }

    public override string ToString()
    {
        return value.ToString();
    }
}

That’s a good start, but I’m not completely satisfied yet:

Can you make it a record so the implementation is more concise? Also, use expression bodied methods for the one-liners.

And now Claude gave me this:

public readonly record struct OrderId : IComparable<OrderId>
{
    private readonly int value;

    public OrderId(int value)
    {
        if (value <= 0)
            throw new ArgumentException("Order ID must be greater than zero", nameof(value));
        this.value = value;
    }

    public int CompareTo(OrderId other) => value.CompareTo(other.value);

    public static bool operator <(OrderId left, OrderId right) => left.CompareTo(right) < 0;
    public static bool operator <=(OrderId left, OrderId right) => left.CompareTo(right) <= 0;
    public static bool operator >(OrderId left, OrderId right) => left.CompareTo(right) > 0;
    public static bool operator >=(OrderId left, OrderId right) => left.CompareTo(right) >= 0;

    public override string ToString() => value.ToString();
}

Finally, I went to Claude and asked this:

Imagine there is an Order class that needs to be saved to the db. We use Entity Framework. How to ensure everything works since this model uses the OrderId type?

And this is my response, complete with the model and the necessary EF configuration to handle our custom type:

// The Order entity
public class Order
{
    public OrderId Id { get; private set; }
    public string CustomerName { get; set; } = default!;
    public decimal TotalAmount { get; set; }
    public DateTime OrderDate { get; set; }

    // Private parameterless constructor for EF
    private Order() { }

    public Order(string customerName, decimal totalAmount)
    {
        CustomerName = customerName;
        TotalAmount = totalAmount;
        OrderDate = DateTime.UtcNow;
    }
}

// Value converter for OrderId
public class OrderIdValueConverter : ValueConverter<OrderId, int>
{
    public OrderIdValueConverter() 
        : base(
            orderId => orderId.GetHashCode(), // Assuming this gets the underlying value
            value => new OrderId(value))
    { }
}

// DbContext configuration
public class OrderDbContext : DbContext
{
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>(builder =>
        {
            builder.HasKey(o => o.Id);
            
            builder.Property(o => o.Id)
                .HasConversion<OrderIdValueConverter>()
                .ValueGeneratedOnAdd(); // Use database auto-increment
            
            builder.Property(o => o.CustomerName)
                .IsRequired()
                .HasMaxLength(200);

            builder.Property(o => o.TotalAmount)
                .HasPrecision(18, 2);
        });
    }
}

Conclusion

This post had two goals. First, to present the concept of tiny types to those of you who had never heard of it. I hope you agree that, despite being a simple idea, the tiny types pattern is something that can help you write code that is more robust.

Second, and more broadly, to demonstrate how LLMs can play an interesting role in fostering better software design. In the past, many software design techniques might have been dismissed as too much work to be worth it. Now, with the help of Claude, ChatGPT, or coding assistants like Copilot, we can streamline the writing of “boring” code, which makes the economics of design techniques such as the one I’ve presented in this post make more sense.

Learning Mistakes to Avoid As a Software Developer

Tue, 22 Oct 2024 00:00:00 +0000

Photo by Francisco De Legarreta C. on Unsplash

ℹ️ Info

Thanks to my friend André Gonçalves da Silva for reading and reviewing earlier drafts of this post

If you work in software development, you’ve certainly heard phrases like “Never stop learning,” “You have to stay updated,” “Our field changes very quickly,” and so on.

Of course, all these phrases are right, to some degree. But going around repeating “never stop learning” like a parrot isn’t the most useful thing in terms of providing direction for your learning.

What often happens in practice is that many people, having never learned how to learn properly, make many learning mistakes that compromise their professional development. These mistakes can lead to slow progress, frustration, and even career stagnation - something nobody wants to experience.

That’s why, in this post, I decided to compile what I believe are the most common learning mistakes that developers generally make. This list is the result of years of personal experience, observation of fellow developers, and many conversations with people in the field. I know what I’m talking about from practical experience because many of these mistakes are things I’ve made myself.

(Being honest, I still make some of them and I’m always having to check myself to stop, but don’t tell anyone. ;))

Identifying and understanding these mistakes is the first step to overcoming them. By avoiding them, you can optimize your learning process, accelerate your professional growth, and stay relevant in a field that’s always evolving.

So, without further ado, here’s the list of learning mistakes to avoid. For each mistake, you’ll see:

the explanation of the mistake
the problem it causes
how to fix it

Let’s go!

Thinking That Content Consumption == Learning
Not Applying the Content from Learning Resources
Lack of Focus
Lack of Consistency
Underestimating the Importance of Fundamentals
Living Under a Rock (Not Keeping Up with What’s Happening)
Conclusion

Thinking That Content Consumption == Learning

I started the list with what I believe to be the most common learning mistake currently, simply because we live in an era where content is produced in massive quantities.

Why Do We Fall Into This Trap?

Consuming content is easy, convenient, and (potentially) fun. Let’s understand why:

Easy: It’s passive, you don’t have to think much or make decisions, and humans tend to seek the path of least resistance.
Convenient: You can usually consume content while doing other things:
- Listen to a podcast while exercising or washing dishes
- Watch a video while eating lunch
- Read posts on Reddit while waiting in line at the bank
Fun: Many creators realize that to engage their audience, they need to add entertainment value and transform the content into a performance that holds attention.

There you have it - the trap is set. Then you go ahead and create a strategy to fill every free moment of your day with podcasts, YouTube videos, blog posts, Reddit, and whatever else.

The Consequences of This Mistake

In the end, you will have:

Consumed your time with superficial information
Retained almost nothing of what you consumed
A vague feeling that you “learned” something

But when it comes to applying this meaningfully in your daily life? That’s where things don’t add up.

Long-term, the consequences can be even more serious:

Professional stagnation, as you’re not really developing new skills
Frustration when realizing you’re not progressing as expected
Possible burnout from constantly trying to “keep up” with everything

To be clear: the mistake here isn’t “consuming content.” It’s thinking that just mindlessly consuming content is enough for you to evolve as a professional.

How to Fix This Mistake

The solution is simple in theory, which doesn’t necessarily mean it’s easy. Here it is:

Decrease the portion of your learning time spent on passive content consumption, and increase the portion spent on practical learning, especially personal projects.

Here are some suggestions:

Create or contribute to an open-source project
Make a website or application for a nonprofit, charitable organization, or your church
Solve a problem that you or a family member has by creating a simple automation
Reinvent the wheel: Implement a known technology or tool (examples: git, Docker, an HTTP server) simply with the goal of learning.

The list above isn’t exhaustive but serves just to start inspiring you. Five minutes of Google or ChatGPT will yield many ideas for cool projects to do.

Not Applying the Content from Learning Resources

If you buy a book and don’t read it, you’re wasting money. If you buy the book, read it, and the learning doesn’t impact how you do your work, then you’re wasting both your money and your time!

The same applies to courses, tutorials, and other learning resources. Being a software developer is a practical profession; how do you expect to benefit from what you’ve learned if you don’t put it into practice?

Before anyone complains: yes, of course there are books, videos, etc., whose content doesn’t have a direct practical application. Maybe you read The Mythical Man-Month to get some insights and learn about software development history, but that doesn’t necessarily change how you write code. And that’s fine, these cases exist – use your common sense.

How does mistake #2 differ from the previous one?

We can summarize the first mistake as “spending 100% of your learning time consuming content.” In other words, you don’t do anything beyond consuming things.

This mistake here is along the lines of “not applying what you learn from the content watched.”

In other words, it’s possible to make the second mistake without making the first one. For example, you might dedicate 60% of your learning time to creating personal projects and 40% to content consumption. But if you still don’t apply in any way the content you learned in those 40% of the time, you’ll have made mistake #2. Is that clear?

Reason for This Mistake

Why do so many people (including yours truly) make this mistake? Probably what happens here is a certain psychological pressure that many of us feel, in terms of hitting numbers. How many people do you know who create goals like this?

Read x technical books per year
Complete y courses by the second semester
etc…

If you really feel like achieving this type of goal, there’s no way around it: you need to “spend” as little time as possible with each piece of content. Otherwise, the math doesn’t work.

Problems Caused By This Mistake

A serious consequence you might suffer from this mistake is lack of motivation. You read all the famous books in the field that were recommended to you, completed all the courses in your IDP, and it seems like nothing changed. It’s hard to stay motivated to persist in learning when it feels like none of it has real impact on how you work.

That’s the frustration with lack of career evolution that we mentioned in the previous mistake. Another serious consequence of this mistake is the waste of time, money, and energy itself: learning is an investment that needs to have a return to be justified.

What’s the Solution?

The remedy for this mistake has two steps:

Prioritize quality over quantity
Constantly apply what you learned

So, here’s my practical suggestion: only start another course/book/etc. after you’ve applied the learning from the previous one.

For example, let’s say you’re taking a Udemy course. After each lesson or section, stop and create a small project where you exercise what you just learned. It doesn’t need to be a big project, or even useful. Preferably, throw it away after you finish: the important thing is the practice.

Here are some more examples:

After watching a programming tutorial, dedicate time to replicate the project on your own, without looking at the video
Read an article about a new refactoring technique? Apply it to a personal project or at work
Heard a podcast about code best practices? Review an old project and see where you can apply these practices

Regarding technical books, I recently created a rule for myself: when I finish a book, I can only start another one after I’ve applied the content of the book I just finished. This application can take different forms:

do the book’s exercises, if it has any
create one or more projects to exercise that content
propose/implement a new practice at work based on what I learned

In the end, that’s what matters: that you find a way to apply the learned content to improve your professional life. A stack of books whose content didn’t impact you only serves to collect dust or as a monitor stand.

Lack of Focus

There are many more “learnable” things than you have time or energy to learn. You’ll never know everything, and you’ll never clear your learning queue. This is a fact and you need to accept and embrace this fact, unless you’re really in the mood for burnout.

Unfortunately, we feel the pressure to “always be studying,” even though that phrase itself isn’t helpful—it offers no guidance about what to study, or what strategies to use.

It’s common for this pressure to come from our own companies:

Read book x!
Take this course!
Complete this learning path!

And these people are well-intentioned, but that doesn’t change the fact that you have a limited amount of time in your day and, more importantly, a limited amount of energy in the time you have available.

But then you give in to the pressure and end up making the mistake of this item: jumping from course to course, book to book, tutorial to tutorial, without ever completing anything, or at least achieving any significant progress.

A Disclaimer

Look: I know that in day-to-day work, it’s very common to encounter a huge number of different problems that need to be solved, and the deadline is always yesterday. In these situations, often the right thing is indeed to learn just the surface level of a topic to be able to handle the demand and generate value for the user as quickly as possible.

The ability to distinguish when it’s time to invest in a certain item more deeply and when surface knowledge is enough is something that’s extremely valuable for any professional’s career, and the only way to perfect this ability is through practice.

The mistake I point out in this item is a different situation from the above scenario. More specifically, the mistake is about trying to learn many things at the same time, in depth, with dense resources.

Problems Caused By This Mistake

The main problem caused by lack of focus is that you never go deep into anything. You end up with a vague impression of knowledge in a million things, but when a critical situation arises where deep knowledge would be necessary, you don’t have anything to show.

As I’ve said before, it’s impossible to go deep into everything. But you should, indeed, go deep into the things that matter most, those that generate the most value for your career. I’m referring to those fundamentals that many people talk about, but I’ll talk more about that in another topic.

How to Fix It

This mistake might be the hardest to fix, because the solution involves a high dose of self-knowledge and a very strong sense of prioritization.

In general, the tip is: define ONE point of evolution for your career, and focus on it for a considerable time, until you evaluate that you’ve made progress.

Some examples of improvement points:

Improve my knowledge of parallelism, concurrency, and performance
Learn the main design patterns and know how to apply them in real projects
Acquire advanced SQL skills
Learn a new language and reach a productive level

It’s not easy to identify this point of improvement, but here are some tips:

Ask for feedback from managers and colleagues.
Talk to a technical mentor you trust.
If you’re actively participating in job interviews and failing, analyze the points where you did poorly in the interviews to identify where to improve.
If you’re not actively looking, pretend you are. Ask a friend or mentor to do a mock interview with you, and then ask for honest feedback.

Lack of Consistency

What’s better, dedicating 30 minutes per day to learning, every day, or 5 hours on the weekend, once every three months? The answer is obvious.

Our profession is practical, deliberate and consistent practice is necessary for you to internalize the things you learn and know how to use them when the time comes.

Consequences

The consequences here are pretty obvious, right? There’s simply no way to make progress if you don’t make consistent effort. This actually applies to pretty much anything in life: physical activity, language learning, playing an instrument, and so on.

If you invest, for example, 1 hour per week to learn something, that gives a total of about 51 hours in the year. Now, if you learn 15 minutes every day, that gives a total of 5,475 minutes in the year, which is more than 91 hours!

Studying just once a week has another disadvantage. If something unexpected comes up and you need to miss it, when you return two weeks will have passed. This way, it becomes complicated to keep the momentum going; you need to remember where you stopped 14 days ago, and regaining the lost context isn’t easy at all.

How to Fix It

Solving this mistake requires thinking about strategies to make learning become a natural part of your daily routine.

To start, define duration: that is, how much time you’ll dedicate daily, in a realistic way. There’s no point in committing to 2 hours of daily learning if your routine simply doesn’t allow it.

Another essential thing is choosing the time of your learning period. To really establish the habit, ideally it would be at the same time every day. When choosing this time, take into consideration how your energy levels change throughout the day. Are you a morning person? Put your learning time in the morning. If not, at night.

I’ll give an example of what works for me. I know that if I leave my learning time for after work, I’ll be too tired and probably won’t do it. So, for me, the best is to reserve about 50 minutes before work for learning.

To make learning a habit, the key is to integrate it into your routine and reduce friction. You know those people who sleep in their gym clothes? Same idea for studying. Leave your PC on with VS Code open in your project, or configure the browser to open directly to the Udemy course. The easier it is to start, the better.

It’s also interesting that the time to decide what to learn and the time to learn be distinct moments. If you have 50 minutes per day for learning, but spend 20 of those minutes every day deciding what to read/practice/watch, you’re wasting 40% of your time.

So here’s the tip: on Saturday, define your learning routine for the following week. You can create a spreadsheet defining the days and what you’ll do, or create a board in Trello, or even use paper and pen, it doesn’t matter. What’s important is that you have this defined beforehand. Then, during the weekdays, you simply check and follow the planning made.

Finally, something that works for many people is making some kind of public commitment. You declare, publicly—for example, on your LinkedIn—that you’ll study without missing for x days. The simple fact of having made this commitment often helps people maintain the routine without missing.

A cool initiative in this sense is 100 Days of Code, which encourages people to code for 100 consecutive days, without fail, interacting with other participants in the process.

Underestimating the Importance of Fundamentals

Many people underestimate the importance of learning computer science fundamentals. Yes, I’m talking about those boring things you didn’t like studying in college: algorithms and data structures, computer theory, algorithm complexity, and so on.

These people argue that you don’t need to know all these things to make your code work. Yes, this might be true most of the time, but not always.

We can think of computing as several layers that abstract the previous layer. When you’re working in one layer, you usually don’t need to worry about the others. This is a good thing, and it’s literally the reason why we use abstractions: to “hide” things that aren’t essential, reducing the complexity of what you need to deal with.

Consequences

Unfortunately, abstractions aren’t perfect. As Joel Spolsky warned us more than 20 years ago, abstractions eventually leak.

In other words: just because you use an ORM doesn’t mean you don’t have to know SQL. Even those who use a managed language like C# or Java can benefit from having an understanding of memory management: at minimum, you’ll be able to write code that uses lifetimes correctly, doesn’t create unnecessary allocations, and puts pressure on the garbage collector.

Lack of understanding of algorithm complexity can bring down a system. You test your code locally with a few hundred values, but when it goes live and has to deal with millions of items, it simply can’t handle it.

In summary: you can make something that “works” without knowledge of fundamentals. However, it works in some scenarios, some of the time, with unacceptable performance, and without taking edge cases into account.

Beyond the problems that lack of a solid foundation can cause in the systems you work on, this mistake can bring another very serious consequence for your career.

Yes, I’m talking about not being able to pass companies’ hiring processes. It’s very common for companies to use technical challenges that require good knowledge in topics like algorithms, data structures, complexity, concurrency and parallelism, the memory model of your preferred language, among others.

Not having this knowledge means being summarily rejected in these processes.

Solution

If you don’t have a college degree, I strongly recommend studying Computer Science. If you’ve already finished college but forgot all those topics, try to remember/reinforce these concepts.

On the internet, you can find plenty of content about Computer Science. For example, the Teach Yourself Computer Science project has a roadmap of topics to learn, with bibliography and video lectures from renowned universities.

NeetCode is a site that provides a roadmap for studying algorithms and data structures. It also offers courses and the ability to practice real questions used in job interviews.

Living Under a Rock (Not Keeping Up with What’s Happening)

I thought it would be interesting if the last mistake was exactly the opposite of the first. While the error that opens the list was “just consuming content and thinking you’re learning,” this one is “never consuming any content at all.”

Why Is This a Problem?

We work in a field that changes constantly, and increasingly quickly. Not staying updated can lead to:

Obsolescence of your skills
Loss of career opportunities
Difficulty in solving problems using more efficient approaches
Lack of inspiration for innovation in your daily work

In other words: lack of updating hurts your performance in your current job, and at the same time reduces your chances of getting a potential new job. That’s not what you want, right?

Finding the Balance

On one hand, using every free second to consume every possible podcast/article/video isn’t a good strategy. It’s like eating lots of junk food: you’ll feel full, but that food won’t bring the benefits your body needs.

But on the other hand, consuming no content is equally bad. As a developer, it’s extremely important that you have at least a notion of what’s happening in the software development world.

What to Keep on Your Radar

Here’s a small list of things that would be interesting to keep on your radar:

Release of technical books about topics you’re interested in, or from authors you already follow
New features in the latest version of your main language or framework
Tools or techniques that can make your life easier
Emerging industry trends (for example, AI)

Where to Find Relevant Content

There are many valuable sources of information for developers. Here are some suggestions:

Reddit:
- r/programming for a general overview
- Specific subreddits like r/csharp, r/java, r/golang, etc.
Hacker News: Excellent for news and discussions about technology in general
YouTube:
- Search for channels related to your specific interests
- Watch technology conference talks
Technical Blogs:
- From technology companies (for example, engineering blogs from Netflix, Spotify, etc.)
- From influential developers in your area
Technology Podcasts: Great for consuming information while doing other activities

Conclusion

We’ve reached the end of the list. I hope this compilation of learning mistakes you just read is useful for your career. With this list I covered what not to do, but what should you do then?

Maybe in the future I’ll write a post just about that: how to learn the right way, and what to focus on. Leave a comment if you’re interested in something like that.

But, for now, to know what to do, just imagine a learning strategy that’s the opposite of the mistakes above:

Learn with consistency, preferably a little every day
Have focus: prioritize one main improvement point at a time
Prefer project-based learning, supplemented in part by content consumption
When consuming content, always apply what you learned in some practical way
Learning about tools is important, but having solid fundamentals is more important

Now comes the most important tip I can leave you with.

Done is better than perfect.

Skipped a day of learning? No big deal, continue the next day. Dedicated 30 minutes to your project instead of the planned 50? That’s still infinitely better than having done nothing.

Trends are more important than data points. Going in the right direction is more significant than arbitrary goals like “I’ll read 6 technical books in 2024.”

It’s difficult to deal with the constant development pressure we feel in this field, I know that well. As much as possible, try to relax. Don’t be too hard on yourself. You’re going in the right direction.

Just the fact that you’ve read to the end of a post of almost 4,000 words shows that you’re much more interested in your development than most. For that, I thank you very much. If you need help, don’t hesitate to get in touch.

Git Detached Head: What This Means and How to Recover

Mon, 16 Sep 2024 00:00:00 +0000

ℹ️ Info

Editorial note: I originally wrote this post for the Cloudbees blog. You can check out the original here, at their site.

Introduction
Reproducing the “Problem”
What Is a HEAD in Git?
- Are you in ‘detached HEAD’ state?
Benefits of a Git Detached HEAD
How Do I Fix a Detached HEAD in Git?
Getting Rid of the “Git Detached HEAD” Message
Conclusion

Introduction

Newcomers to Git often get confused with some of the messages that the VCS tool throws at them. The “You are in ‘detached HEAD’ state” one is certainly one of the weirdest. After coming across this message, most people start furiously Googling “git detached HEAD,” “git detached HEAD fix,” or similar terms, looking for anything that might be of help. If that’s your case, you’ve come to the right place.

Here’s the first thing you should know: you haven’t done anything wrong. Your repo isn’t broken or anything like that. The expression “Detached HEAD” might sound somewhat bizarre, but it’s a perfectly valid repository state in Git. Sure, it’s not the normal state, which would be—you’ve guessed it!—when HEAD is attached. The second thing you need to know is that going back to normal is super easy. If you just want to do that and get on with your day, go to the “How Do I Fix a Detached Head in Git?” section of this post to see how it’s done.

But if you want to know more—and I guess you do—stick around and we’ll help you. What does HEAD mean in Git? What does it mean for it to be attached or detached? These are the kind of questions we’ll answer in this post. By the end of it, you’ll have a better understanding of Git’s fundamentals, and detached HEADs will never trouble you again. Let’s dig in.

Git Detached HEAD: Reproducing the “Problem”

Let’s start with a quick demo showing how to reach the detached HEAD state. We’ll create a repository and add some commits to it:

mkdir git-head-demo
cd git-head-demo 
git init
touch file.txt
git add .
git commit -m "Create file"
echo "Hello World!" > file.txt
git commit -a -m "Add line to the file"
echo "Second file" > file2.txt
git add .
git commit -m "Create second file"

With the commands above, we’ve created a new folder with a new repository inside it. Then we created a new empty file and committed that with the message “Create file.” Next, we added a line to that file and committed the change, with the message “Add a line to the file.” Finally, we’ve created another file with one line of text and committed that as well. If you use the git log –oneline command, you’ll see something like this:

Let’s say that, for testing purposes, we need to see how things were at the time of the second commit. How would we do that? As it turns out, we can check out a commit the same way we’d check out branches. Remember, branches are just names for commits. So, based on the example output above, we’d run git checkout 87ec91d. Keep in mind that if you’re following along by executing these commands on your own system, the hash for your commits will be different from those in the example. Use the log command to find it.

After running the command, we get the “You are in ‘detached HEAD’ state[…]” message. Before we go on, make sure you keep this in mind: you get to the detached HEAD state by checking out a commit directly.

What Is a HEAD in Git?

What does HEAD mean in Git? To understand that, we have to take a step back and talk fundamentals.

A Git repository is a collection of objects and references. Objects have relationships with each other, and references point to objects and to other references. The main objects in a Git repository are commits, but other objects include blobs and trees. The most important references in Git are branches, which you can think of as labels you put on a commit.

HEAD is another important type of reference. The purpose of HEAD is to keep track of the current point in a Git repo. In other words, HEAD answers the question, “Where am I right now?”

For instance, when you use the log command, how does Git know which commit it should start displaying results from? HEAD provides the answer. When you create a new commit, its parent is indicated by where HEAD currently points to.

Are you in ‘detached HEAD’ state?

You’ve just seen that HEAD in Git is only the name of a reference that indicates the current point in a repository. So, what does it mean for it to be attached or detached?

Most of the time, HEAD points to a branch name. When you add a new commit, your branch reference is updated to point to it, but HEAD remains the same. When you change branches, HEAD is updated to point to the branch you’ve switched to. All of that means that, in these scenarios, HEAD is synonymous with “the last commit in the current branch.” This is the normal state, in which HEAD is attached to a branch.

A visual representation of our demo repository would look like this:

As you can see, HEAD points to the master branch, which points to the last commit. Everything looks perfect. After running git checkout 87ec91d, the repo looks like this:

This is the detached HEAD state; HEAD is pointing directly to a commit instead of a branch.

Benefits of a Git Detached HEAD

Are there good reasons for you to be in the detached HEAD state? You bet there are!

As you’ve seen, you detach the HEAD by checking out a commit. That’s already useful by itself since it allows you to go to a previous point in the project’s history. Let’s say you want to check if a given bug already existed last Tuesday. You can use the log command, filtering by date, to start the relevant commit hash. Then you can check out the commit and test the application, either by hand or by running your automated test suite.

What if you could not only take a look at the past, but also change it? That’s what a detached HEAD allows you to do. Let’s review how the detached message starts:

You are in 'detached HEAD' state. 
You can look around, make experimental changes and commit them,
and you can discard any commits you make in this state without
impacting any branches by switching back to a branch.

In this state, you can make experimental changes, effectively creating an alternate history. So, let’s create some additional commits in the detached HEAD state and see how our repo looks afterward:

echo "Welcome to the alternate timeline, Morty!" > new-file.txt
git add .
git commit -m "Create new file"
echo "Another line" >> new-file.txt
git commit -a -m "Add a new line to the file"

We now have two additional commits that descend from our second commit. Let’s run git log –oneline and see the result:

This is what the diagram looks like now:

What should you do if you want to keep those changes? And what should you do if you want to discard them? That’s what we’ll see next.

How Do I Fix a Detached HEAD in Git?

You can’t fix what isn’t broken. As I’ve said before, a detached HEAD is a valid state in Git. It’s not a problem. But you may still want to know how to get back to normal, and that depends on why you’re in this situation in the first place.

Scenario #1: I’m Here by Accident

If you’ve reached the detached HEAD state by accident—that is to say, you didn’t mean to check out a commit—going back is easy. Just check out the branch you were in before:

git checkout <branch-name>

If you’re using Git 2.23.0 or newer, you can also use switch instead of checkout:

git switch <branch-name>

Scenario #2: I’ve Made Experimental Changes and I Want to Discard Them

You’ve entered the detached HEAD state and made a few commits. The experiment went nowhere, and you’ll no longer work on it. What do you do? You just do the same as in the previous scenario: go back to your original branch. The changes you made while in the alternate timeline won’t have any impact on your current branch.

Scenario #3: I’ve Made Experimental Changes and I Want to Keep Them

If you want to keep changes made with a detached HEAD, just create a new branch and switch to it. You can create it right after arriving at a detached HEAD or after creating one or more commits. The result is the same. The only restriction is that you should do it before returning to your normal branch.

Let’s do it in our demo repo:

git branch alt-history
git checkout alt-history

Notice how the result of git log –oneline is exactly the same as before (the only difference being the name of the branch indicated in the last commit):

We could just run git branch alt-history, and we’d be all set. That’s the new—and final—version of our diagram:

Getting Rid of the “Git Detached HEAD” Message

Before wrapping up, let’s share a final quick tip. Now that you understand everything about detached HEAD in Git and know that it’s not that big of a deal, seeing that message every time you check out a commit might become tiring. Fortunately, there’s a way to not see the warning anymore. Just run the following command:

git config advice.detached head false

Easy, right? You can also use the –global modifier if you want the change to apply to every repository and not only the current one.

Git Detached HEAD: Less Scary Than It Sounds

A message talking about heads not being attached doesn’t sound like your routine software error message, right? Well, it’s not an error message.

As you’ve seen in this post, a detached HEAD doesn’t mean something is wrong with your repo. Detached HEAD is just a less usual state your repository can be in. Aside from not being an error, it can actually be quite useful, allowing you to run experiments that you can then choose to keep or discard.

Would you like to learn more about Git? Check-out some of the following posts:

Thanks for reading!

C# Regex: How Regular Expressions Work in C#, With Examples

Tue, 07 May 2024 00:00:00 +0000

Editorial note: I originally wrote this post for the Stackify blog. You can check out the original here, at their site.

Text manipulation is one of the most common tasks in programming with virtually all major programming languages usually supporting regex (regular expression) via their standard libraries. C# is no exception, so today we bring you a C# regex guide.

You’ll learn what regexes are, why you’d want to use them and how to get started in a comprehensive, approachable manner. That way, you can start using regular expressions to solve real problems ASAP.

Buckle up for your regex learning journey, starting now!

What Is Regex?

A regular expression (regex) is an expression containing one or many characters that expresses a given pattern in text. If that sounds a little vague, an example will help. Consider a date in the following format:

28-JUL-2023

Using a regex, we can express that format like this:

[0-9]{2}-[A-Z]{3}-[0-9]{4}

Note that the regular expression above expresses a pattern with:

two numeric digits followed by a hyphen
three upper-case letters followed by a hyphen
four more numbers

You’ll learn more about what each part of a regex means in a minute. For now, just bear in mind that the regex above doesn’t know anything about dates. It just happens that we were able to devise a regular expression that matches the pattern or shape of the date. All of the following match with that regex, even though they’re not valid dates:

32-ABC-7894
30-FEV-1978
00-AAA-9999

Is There Regex in C#?

Yes, of course. But that doesn’t come from the language itself. Instead, regex support comes from .NET’s BCL (Base Class Library), which is essentially C#’s standard library.

Why Use Regex In C#?

As you’ve seen, regex is something to use to express a pattern that can match a given text.

In practice, all uses of regex in C# or other languages boil down to three reasons: validation, manipulation and extraction.

Validation

An incredibly common use case for regex is data validation. For instance, let’s say you have a web form and want to ensure a certain field only accepts inputs in a specific format. How to solve that? Regex comes to the rescue.

Manipulation

Sometimes you need to change information within text. Let’s go back to the previous example. Imagine for compliance reasons you need to remove all phone numbers from this body of text and replace them with the word “REDACTED.” Again, regexes would be a perfect fit for this situation.

Interestingly, programming languages are not alone in using regular expressions to solve problems. Even text editors such as Notepad++ offer find-and-replace features powered by regexes.

Extraction

Let’s say you have considerable amounts of text. This text contains telephone numbers that you need to extract. You know the format of those numbers and the fact that they’re inside the text, but that’s the extent of your knowledge.

How would you go about extracting that information? A neat C# regex would certainly come in handy in that situation.

How to Use Regex In C#: Getting Started in Practice

C# is an OOP language, so it shouldn’t be a surprise that you’ll use a class for your C# regex work. More specifically, the class I’m talking about is appropriately called Regex and resides in the System.Text.RegularExpressions namespace.

C# Regex: A Validation Example

Let’s start with a simple validation example on how to use regex to validate whether several strings match a given pattern. The first step is to add the following using statement to your code:

using System.Text.RegularExpressions;

Now, let’s create an array of strings and populate it with some values:

var candidates = new[]
{
    "28-JUL-2023",
    "whatever",
    "89-ABC-1234",
    "11-JUN-2022",
    "11-JUN-2022, a date plus other stuff",
    "This is certainly not a date"
};

Finally, we’ll loop through the values and use the IsMatch static method from the Regex class to verify which of the strings matches our desired pattern:

var pattern = "[0-9]{2}-[A-Z]{3}-[0-9]{4}";
foreach (var c in candidates)
{
    if (Regex.IsMatch(c, pattern))
    {
        Console.WriteLine($"The string '{c}' matches the pattern '{pattern}'");
    }
}

Before going further, let’s break down the pattern piece by piece:

[0-9]{2}: The first part means “Match exactly two characters, that must be digits from 0 to 9.”
-: This character matches exactly a hyphen.
[A-Z]{3}: Here, the expression says, “Let’s match exactly three characters, which can be any of the letters from A to Z.”
-: This matches another hyphen
[0-9]{4}: This should be easy to understand by now, right? Exactly four numbers.

Now, let’s run the code and see what we get:

The string '28-JUL-2023' matches the pattern '[0-9]{2}-[A-Z]{3}-[0-9]{4}'
The string '89-ABC-1234' matches the pattern '[0-9]{2}-[A-Z]{3}-[0-9]{4}'
The string '11-JUN-2022' matches the pattern '[0-9]{2}-[A-Z]{3}-[0-9]{4}'
The string '11-JUN-2022, a date plus other stuff' matches the pattern '[0-9]{2}-[A-Z]{3}-[0-9]{4}'

The first three results probably didn’t surprise you. I even include something that’s not a date but matches the pattern we’re using in order to really drive home the point that regular expressions are about patterns and shapes and not about any semantics of the data we’re looking for.

However, the fourth result might’ve surprised you. The text indeed starts with data that matches the pattern we’re looking for, but then it has some additional text. And even then, this string matched!

The explanation for this behavior is simple, and it’s spelled out for us in the summary for the IsMatch method:

Indicates whether the specified regular expression finds a match in the specified input string.

The regular expression indeed found a match in the specified input string (“11-JUN-2022, a date plus other stuff”), and that’s why it was considered a match.

But what if we wanted an exact match? In that case, you’d have to change the pattern, adding a circumflex accent (“^”) to the star of the pattern and a dollar sign (“$”) to its end. In other words, here’s how the pattern should look now:

var pattern = "^[0-9]{2}-[A-Z]{3}-[0-9]{4}$";

If we run the code now, it displays only the strings that are an exact match with the pattern:

The string '28-JUL-2023' matches the pattern '^[0-9]{2}-[A-Z]{3}-[0-9]{4}

C# Regex: A Manipulation Example

Consider you have a body of text containing sensible user data. Due to privacy/compliance concerns, you want to redact those data points. Luckily for you, it’s quite easy to use a regex for that.

Let’s start by creating an array containing names and phone numbers for fictitious people:

var contacts = new[] {
    "Emily Johnson,(555) 123-4567",
    "Benjamin Williams,(555) 987-6543",
    "Olivia Davis,(555) 222-3333",
    "Alexander Smith,(555) 444-5555",
    "Sophia Brown,(555) 777-8888",
    "William Anderson,(555) 111-2222",
    "Ava Martinez,(555) 666-7777",
    "James Thompson,(555) 888-9999",
    "Isabella Wilson,(555) 333-4444",
    "Michael Taylor,(555) 777-1111"
};

Then, let’s create the pattern to match the phone numbers:

var pattern = @"\([0-9]{3}\)\s[0-9]{3}-[0-9]{4}";

The pattern above is a bit more involved than the ones we used earlier, but it’s still simple. There are a couple of new elements, though:

The backward slash (\): We need it here in order to escape the opening and closing parenthesis, which is a character with meaning in a regular expression. In this instance, we actually do want to match a “(” character, so we need to escape it.
The \s character: matches a single space.

Finally, let’s loop through this array and, for each item, use the Regex.Replace method to generate a new string in which the phone number is replaced by all zeroes:

foreach (var contact in contacts)
{
    Console.WriteLine(
        Regex.Replace(contact, pattern, "(000) 000-0000"));
}

Using the Replace static method is easy. Though it has several overloads, the one we use just takes three arguments:

the input string
the pattern you want to match
the replacement string

After running the code, here’s the output we get:

Emily Johnson,(000) 000-0000
Benjamin Williams,(000) 000-0000
Olivia Davis,(000) 000-0000
Alexander Smith,(000) 000-0000
Sophia Brown,(000) 000-0000
William Anderson,(000) 000-0000
Ava Martinez,(000) 000-0000
James Thompson,(000) 000-0000
Isabella Wilson,(000) 000-0000
Michael Taylor,(000) 000-0000

C# Regex: An Extraction Example

For our last example, let’s extract data from a string using a regular expression. Let’s start by converting the array from the previous example into a single string:

var contacts =
    "Emily Johnson+(555) 123-4567" +
    "\nBenjamin Williams+(555) 987-6543" +
    "\nOlivia Davis+(555) 222-3333" +
    "\nAlexander Smith+(555) 444-5555" +
    "\nSophia Brown+(555) 777-8888" +
    "\nWilliam Anderson+(555) 111-2222" +
    "\nAva Martinez+(555) 666-7777" +
    "\nJames Thompson+(555) 888-9999" +
    "\nIsabella Wilson+(555) 333-4444" +
    "\nMichael Taylor+(555) 777-1111";

Then, we define the pattern again (same one) and use the Matches static method to get all of the matches from the string:

var pattern = @"\([0-9]{3}\)\s[0-9]{3}-[0-9]{4}";
MatchCollection matches = Regex.Matches(contacts, pattern);

The MatchCollection class holds all of the strings that matched the pattern we gave to the method. This object is enumerable, so we can loop over it with a foreach:

Console.WriteLine("Here are the extracted phone numbers:");
foreach (Match match in matches)
{
    Console.WriteLine(match.Value);
}

And, finally, our results:

Here are the extracted phone numbers:
(555) 123-4567
(555) 987-6543
(555) 222-3333
(555) 444-5555
(555) 777-8888
(555) 111-2222
(555) 666-7777
(555) 888-9999
(555) 333-4444
(555) 777-1111

C# Regex: An Indispensable Tool

As we said in the intro, text manipulation is a staple of programming, and regular expressions make this task easier. In this C# regex guide, you’ve learned what regular expressions are, their most common usage scenarios and how to get started with regular expressions in C#.

Before departing, a few tips:

Experiment more with the Regex class. It offers plenty of features, and the methods we’ve used today have many overloads with useful capabilities.
Learn more and practice writing regular expressions. Here’s a great site you can use.
Educate yourself on the performance considerations of C# regex. For instance, read this Microsoft article on the compilation and reuse of regular expressions.

Finally, if you want to learn more about C# in general, you’re in the right place. The Stackify blog is full of useful resources. As a suggestion, take a look at the pros and cons of the top 3 unit test frameworks for C#, how to catch exceptions and find application errors in C#, and how C# reflection works next.

Thanks for reading!

carlos schults / blog

Building git in Go From Scratch - Part 2

It’s Been a While

Plumbing vs Porcelain Commands

Understanding hash-object And cat-file

Hashing Your First Object

Saving an Object

Reading Objects Back

Enter Go-Gitter

Implementing hash-object

Implementing cat-file

What I’ve Learned So Far

What’s Next?

Your Commit Messages Suck. Let Me Show You How To Fix That

Your commit Messages Suck Because…

…You Only Care About Coding

…Sometimes You Don’t Understand What You’re Doing

…Writing Is Hard

…Nobody Has Taught You

…GitHub Taught You Bad Habits

…Git’s -m Option Trained You Poorly

…You Don’t Have Proper Commit Hygiene

Taxonomy of Bad Commit Messages

Almost Useless One-Liner

Useless One-Liner

Ticket System Reference Only

The Misleading One-Liner

You Will Write Great Commit Messages When You…

…Stop Writing One-Liners

…Lead With The “What”, Expand With The “Why” and “How”

…Follow the 50/72 Rule

…Adopt Atomic Commits

…Commit Often, Perfect Later

Examples of Great Commit Messages

AI Changes Everything. Or…Does It?

Conclusion

Implementing git in Go From Scratch, For Fun and...Profit?

Project Scope

Project Workflow (I really didn’t know what to call this section)

About LLM Usage

Building git in Go: The First Update

Follow the Updates

What Are Breaking Changes?

What is a breaking change?

Examples of Breaking Changes

New Required Parameters

Removed optional parameters or made them required

New Members Added To An Interface

Changed the Type of a Method Parameter

Changed return type of a method or function

Changed parameter order

Modified error handling behavior (throwing different exceptions)

Made public methods or properties private

Added authentication requirements where none existed

Added new required properties to a payload

Rename or delete an endpoint

What to do about breaking changes?

Gradually Deprecation

Add Instructions to Your Release Notes

Use Semantic Versioning

Conclusion

How to Improve Developer Experience: 7 Things to Change

What’s Developer Experience? Why Should You Care?

Developer Experience: Improve It With These 7 Tips

1. Minimize Interruptions

2. Invest in Technical Excellence

3. Give Developers Autonomy

4. Remove the Friction When Creating Development Environments

5. Invest in Developer Education

6. Don’t Be Cheap When It Comes to Tools

7. Listen to Developers’ Feedback (and Act Upon It)

Improve Developer Experience, Improve Your Company

Git Switch Branch: Everything You Need to Know

How Do Git Branches Work?

How Do I Create a New Branch?

How Do You Switch Branches?

How Do I Use Git Checkout?

What Is Git Switch?

How Do I Switch to a Remote Branch?

Git Branches: Use in Moderation

Understanding `hash-object` And `cat-file`

Implementing `hash-object`

Implementing `cat-file`

…Git’s `-m` Option Trained You Poorly