The gdenticon Refactoring Log — Part 1
What gdenticon is
gdenticon is an identicon generator I wrote in Go. Give it a username, email address, or another string, and it produces a stable pixel avatar. The same input gives the same result, which makes it useful as a default image when a user has not uploaded one.
The project already works as both a command-line tool and a Go package. It can output PNG, SVG, JPEG, GIF, BMP, and TIFF.
This series, however, is not an introduction to a finished project. I am going back through it and refactoring parts of it.
Why gdenticon exists
I started the project because the Go identicon libraries I could find never quite matched what I needed.
Some produced patterns that felt too dense. Some were effectively limited to PNG. Others required more setup code than I wanted for generating one small avatar.
That did not make those projects bad. They were simply designed around needs that were different from mine. I wanted a smaller tool with calmer-looking patterns, flexible output formats, a convenient CLI, and an API that could be dropped into another Go project without much preparation.
After failing to find exactly that, I decided to build it. That was the beginning of gdenticon.
Why refactor something that already works
Avatar generation is already implemented, but working features do not automatically mean the current solution is good enough.
As the project grew, I began to notice problems that did not appear as immediate failures. Some responsibilities were not separated clearly enough, so changing one area meant thinking about several others. Pattern generation still had room to become more efficient. Supporting more output formats and ways to use the package also made the original organisation less comfortable.
None of this stops the program from producing an avatar today. It does affect how easily the project can change tomorrow.
I would rather address that while the codebase is still small than wait until every new feature has to work around an old decision. The refactoring is therefore not a rewrite from scratch, and it is not an excuse to introduce a more elaborate architecture.
The working behaviour will remain. The goal is to make responsibilities clearer, remove unnecessary computation and memory use, keep the API simple, and make later changes to formats and pattern generation less disruptive.
What I want gdenticon to become
My expectation for gdenticon has not changed. It should remain a small, practical tool rather than a collection of abstractions built to demonstrate techniques.
Generating an avatar should take very little code. The tool should feel natural in a terminal and inside a web service, background job, or another Go project. Results should be deterministic, patterns should not feel overcrowded, and the output should not be tied to one image format.
The inside of the project should be approachable as well. Someone opening the repository for the first time should be able to follow how input becomes an avatar. Adding a format or adjusting the pattern should not require understanding every package. When something fails, its owner should be reasonably easy to locate.
Performance is part of this work, but I do not want to label the project as fast before measuring it. Each optimisation should come with a reproducible test. If an idea makes little difference, that result is worth recording too. Clever-looking code is not evidence of an improvement.
Recording the process this time
When working on a small personal project, it is easy to focus on getting the feature finished. The reasoning behind a design, the alternatives that were tried, and the decisions that were later reversed often feel unforgettable at the time. A few months later, much of that context is gone.
This time I want to keep the process alongside the code. The series will cover not only the final implementation, but also the problem behind each change, the alternatives I did not choose, and whether the measurements matched my expectations.
Later parts will move through the program entry and error handling, the split between generation and output, the avatar pattern, benchmarks, and other issues that appear during the refactoring. Each part will stay with one main problem instead of trying to explain the entire project at once.
There will be blind spots in a one-person project. If you find a weakness in the code or see a better direction, I would be glad to hear it.
GitHub Repository: https://github.com/hourinX/gdenticon
Next
The next part will start with the overall structure and follow one avatar request from the program entry to the final encoded image.
Top comments (0)