Code Quality on

Lesson 10: Over-Engineering CRUD — Not every API needs a hexagonal architecture

Wed, 02 Jul 2025 00:00:00 +0000

There is a category of service that I have built many times and will build many more times: an API that creates, reads, updates, and deletes records in a relational database, with some validation and authentication. There is nothing glamorous about it, and there is nothing architecturally complex about it either. The correct implementation is straightforward, fast to build, easy to test, and easy to read. The over-engineered implementation has event sourcing, CQRS, a message bus, six layers of abstraction, and takes three months to build something that the straightforward implementation would have shipped in two weeks.

Lesson 8: Linting with golangci-lint — Automate what reviewers shouldn''t waste time on

Sun, 01 Jun 2025 00:00:00 +0000

I made a rule for myself a few years ago: if I leave a code review comment about something a tool could have caught, I’ve wasted both the author’s time and mine. A linter can catch unused variables, missing error checks, shadowed variables, inefficient string concatenation, and dozens of other patterns automatically — in seconds, every commit, without reviewer fatigue. The code review should be about design and correctness, not about whether someone forgot to handle an error returned by rows.Close().

Lesson 9: Fake Clean Architecture — Layers without purpose are just folders

Tue, 20 May 2025 00:00:00 +0000

I cloned a Go repository that was described to me as a “clean architecture” implementation. It had six layers: handler, usecase, service, repository, model, and dto. Every user-related operation required touching at least four files across four packages. When I added a new field to the user profile, I updated the database schema, the model.User, the dto.UserDTO, the repository.UserRepository, the service.UserService, the usecase.UserUseCase, and the handler.UserHandler. Eight files for one field. The indirection was total, the business logic was nowhere — it was scattered across the layers in thin delegating functions that called the layer below and returned the result.

Lesson 10: Using unsafe to Escape the Borrow Checker — The wrong reason

Thu, 24 Apr 2025 09:30:00 +0000

I found this in a production codebase:

fn get_or_insert(&mut self, key: &str) -> &mut Value {
 if !self.map.contains_key(key) {
 self.map.insert(key.to_string(), Value::default());
 }
 // "The borrow checker is being stupid, we know the key exists"
 unsafe { &mut *(self.map.get_mut(key).unwrap() as *mut Value) }
}

The comment says it all. The developer hit a borrow checker error — a legitimate one about borrowing self.map mutably twice — and instead of restructuring the code, they cast through a raw pointer to silence the compiler. This is undefined behavior. The compiler is allowed to assume the mutable references don’t alias, and it will optimize based on that assumption. When it does, your program does something you didn’t write.

Lesson 9: Macro Abuse — When a function would do

Mon, 21 Apr 2025 17:08:00 +0000

I spent an entire afternoon debugging a test failure that turned out to be caused by a macro expanding variable names in a way I didn’t expect. The macro was called make_handler! and it generated HTTP handler functions from a declarative DSL that someone on the team had invented. The “DSL” saved maybe ten lines of boilerplate per handler. The macro definition was 200 lines of nested macro_rules! with five recursion levels, three tt munchers, and hygiene workarounds that I’m still not convinced were correct. When a new developer asked how to add a query parameter to a handler, nobody could explain it without first teaching them how the macro worked.

Lesson 8: Premature Optimization — Profile before you optimize

Sat, 19 Apr 2025 13:42:00 +0000

A teammate once spent three days replacing every String in our data model with a custom arena-allocated string type. The rationale: “String allocations are slow, and we’re processing a lot of data.” Sounds reasonable, right? After the rewrite, I ran the benchmarks. The improvement was within noise — less than 1%. The actual bottleneck was network I/O to an external API, which accounted for 94% of the request latency. Those three days of intricate unsafe string manipulation? Completely wasted. And the code was now harder to read, harder to maintain, and had a subtle use-after-free bug that we found six weeks later.

Lesson 7: Arc> as Default — Reach for channels first

Wed, 16 Apr 2025 20:15:00 +0000

There’s a specific moment in every Rust developer’s journey where they discover Arc<Mutex<T>> and start putting everything in it. I’ve been that developer. I had a web service that needed to share a cache between request handlers, and my first instinct was Arc<Mutex<HashMap<String, CachedItem>>>. It worked. Then traffic went up, contention went up, tail latency went up, and I spent a weekend profiling lock contention that shouldn’t have existed in the first place — because most of my “shared mutable state” could have been restructured as message passing.

Lesson 6: Trait Bloat — Interface segregation in Rust

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

I worked on a project that had a Storage trait with twenty-three methods. Twenty-three. It handled reading, writing, deleting, listing, searching, watching for changes, managing permissions, computing checksums, and streaming large files. Every backend — S3, local filesystem, in-memory for tests — had to implement all twenty-three methods. The in-memory test backend had fourteen methods that just returned unimplemented!(). The local filesystem backend panicked on the permissions methods because POSIX permissions don’t map to the trait’s model. And every time someone added a new method to the trait, every backend had to be updated — even the ones where the new method made no sense.

Lesson 5: Over-Genericizing — Not everything needs

Sun, 13 Apr 2025 11:28:00 +0000

I reviewed a library last year where the author had made literally everything generic. The HTTP client was generic over the transport, the serializer, the deserializer, the error type, the retry policy, the timeout strategy, and the logger. Using it required spelling out a type signature that looked like this:

let client: HttpClient<
 TcpTransport<TlsConfig>,
 JsonSerializer<PrettyPrint>,
 JsonDeserializer<StrictMode>,
 AppError,
 ExponentialBackoff<SystemClock>,
 FixedTimeout,
 SlogLogger<JsonFormat>,
> = HttpClient::new(/* ... */);

The kicker? The library was an internal tool used by exactly one team. There was one transport, one serializer, one error type. Every type parameter had exactly one implementation. The author had written an extensible framework for a problem that didn’t need extending.

Lesson 4: God Structs — When types do too much

Fri, 11 Apr 2025 16:10:00 +0000

I once opened a file called app.rs and found a struct with forty-two fields. Forty-two. It held the database connection, the HTTP client, the cache handle, the logger, the config, the metrics collector, the rate limiter, the auth provider, the feature flags, the email sender, the template engine, and about thirty other things I’ve blocked from memory. Every function in the codebase took &self on this monster. Need to send an email? You need the god struct. Parse a config value? God struct. Log a message? Believe it or not, god struct.

Lesson 3: Stringly Typed APIs — Use enums, not strings

Wed, 09 Apr 2025 08:47:00 +0000

I inherited a Rust codebase once where the entire state machine was driven by string comparisons. The order status could be "pending", "processing", "shipped", "delivered", or "cancelled". Except sometimes it was "Pending" with a capital P. And there was one code path that set it to "canceled" — one L, American spelling. And another that used "CANCELLED". The bug lived in production for weeks because nobody could figure out why some orders were getting stuck in a phantom state that didn’t match any of the if status == "cancelled" checks scattered across thirty files.

Lesson 2: unwrap() in Production — Time bombs waiting to explode

Mon, 07 Apr 2025 14:35:00 +0000

A service I was responsible for went down at 2 AM on a Saturday because of a single .unwrap() call on line 847 of a file nobody had touched in months. The function parsed a config value that was supposed to always be present. Somebody changed the config format in a different repo, the value became optional, and that .unwrap() detonated like a landmine — thread 'main' panicked at 'called Option::unwrap() on a None value'. Down. Dead. Pager screaming.

Lesson 1: .clone() Everywhere — Hiding ownership problems

Sat, 05 Apr 2025 10:22:00 +0000

I was reviewing a pull request last year from a developer who’d been writing Rust for about three months. The code compiled. The tests passed. Everything looked fine — until I ran grep -c '\.clone()' src/ and got back a number that made me physically uncomfortable. Forty-seven clones across six files. The codebase was a data pipeline processing millions of events per hour, and this person had turned every ownership error into a .clone() call until the compiler stopped yelling.

Lesson 8: Premature Abstraction — Wrong abstraction costs more than duplication

Wed, 02 Apr 2025 00:00:00 +0000

There is a principle in software development — “Don’t Repeat Yourself” — that is so widely known it gets abbreviated to DRY and invoked to justify almost any abstraction. The problem is that DRY is a principle about knowledge, not syntax. Two pieces of code that look the same but represent different concepts should stay separate. Two pieces of code that represent the same concept should indeed be unified. Most premature abstractions happen when developers see syntactic similarity and immediately reach for abstraction, before they understand whether the similarity is incidental or fundamental.

Lesson 7: Kill the Utils Package — util.go is where code goes to hide

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

Every Go codebase I’ve worked on for more than a year has a util package. Some have a helpers package. Some have both. I’ve seen common, shared, misc, and once, memorably, stuff. These packages are where code goes when a developer doesn’t know where it belongs — which means they’re the first place reviewers stop reading carefully, the last place new engineers look when they can’t find something, and the primary location of dead code in any codebase over 18 months old.

Lesson 7: Panic as Error Handling — Panic is for bugs, not business logic

Tue, 18 Feb 2025 00:00:00 +0000

I have reviewed Go code from developers who learned other languages where exceptions are the primary error handling mechanism. In Ruby, Python, or Java, you throw an exception and it propagates up the stack until something catches it. In Go, the analogous mechanism — panic — has a very different contract. A panic that is not recovered crashes the entire process. In a web server, that means every in-flight request dies. In a worker process, that means all queued work is dropped.

Lesson 6: Package Cohesion — Everything in a package should belong together

Thu, 06 Feb 2025 00:00:00 +0000

Go packages are the primary unit of code organization. They determine what’s visible to whom, what gets compiled together, and — most importantly — they communicate intent to every engineer who reads the codebase. A package with high cohesion says something true and useful: “everything here is about orders” or “everything here handles HTTP middleware.” A package with low cohesion says nothing — it’s a filing cabinet where things went when nobody knew where else to put them.

Lesson 6: Swallowing Errors — The silent failure that cost us 3 hours

Sun, 12 Jan 2025 00:00:00 +0000

We had a deployment where user preferences stopped being saved. New preferences were accepted by the API — the endpoint returned 200 — but nothing was written to the database. After three hours of debugging we found it: a defer rows.Close() inside a transaction helper that was discarding the error from tx.Commit(). The commit was failing silently, the defer returned without error, and the handler sent a success response. The only indication anything was wrong was a metrics counter nobody had set up an alert for.

Lesson 5: Small Functions Win — If you can''t name it clearly, it does too much

Fri, 06 Dec 2024 00:00:00 +0000

There is a simple test I apply to any function I’m about to merge: can I name it clearly without using “and”? If the most honest name for a function is validateAndSaveAndNotifyUser, the function is three functions pretending to be one. The naming test doesn’t lie — it’s a direct readout of the function’s responsibility. I’ve seen this test convince engineers who were unmoved by SOLID principles or Uncle Bob quotes, because it’s visceral: if you can’t say what the function does in a few words, you already know something is wrong.

Lesson 5: Ignoring Context — The cancellation nobody checked

Fri, 22 Nov 2024 00:00:00 +0000

I spent a Tuesday afternoon tracking down why our service continued doing expensive database work after clients had long since disconnected. An HTTP client with a 3-second timeout would cancel the request, but our handler would still run three downstream database queries that together took 8 seconds. The handler was checking for errors but never checking the context. By the time it finished, the client had retried twice, and we were now running three copies of the same 8-second work simultaneously.

Lesson 4: Code Review Heuristics — What to look for in a Go PR

Sun, 20 Oct 2024 00:00:00 +0000

A good code review is not a diff-reading exercise. It’s a transfer of understanding — the reviewer asks “do I understand what this code does, why it does it, and what it doesn’t do?” If the answer to any of those is no, that’s a comment, not a nitpick. I’ve done hundreds of Go reviews and the feedback I give clusters into the same ten or fifteen patterns so reliably that I eventually wrote them down as a checklist. This lesson is that checklist, with examples.

Lesson 4: Channel Misuse — You used a channel where a mutex would do

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

Go’s channels are genuinely great. They make certain concurrent programming patterns — pipelines, fan-out, fan-in, worker pools — natural and readable. Because they are idiomatic and distinctly Go-like, there is a tendency among Go developers to reach for them first whenever concurrency is involved. The result is code that uses channels to protect shared state, which is what mutexes are for, or code that passes one value through a channel with ceremony that could be replaced by a function call.

Lesson 3: Global Mutable State — The variable that breaks every test

Thu, 05 Sep 2024 00:00:00 +0000

There was a test suite I worked on where tests passed individually but failed when run together. The failure pattern was non-deterministic — sometimes test A broke test B, sometimes test C broke test A, and it changed with the -count flag. After two hours of bisecting, we found it: a package-level var config Config that every test modified by calling loadConfig("testdata/some-fixture.json"). The tests were sharing state without knowing it, and the one that ran last set the config for all the others.

Lesson 3: Idiomatic Naming — Names are your documentation

Wed, 04 Sep 2024 00:00:00 +0000

When I review Go code, naming problems tell me more about the author’s understanding of the codebase than almost anything else. A function called HandleRequest that parses JSON, queries a database, formats a response, and writes to a log tells me its author didn’t know what it does either. A variable called data in a function that handles three different kinds of data tells me the author stopped thinking halfway through. Names are the first layer of documentation — they’re read far more often than comments, and unlike comments, they can’t drift out of sync with the code.

Lesson 2: Giant God Structs — If your struct has 30 fields, it has 30 problems

Thu, 25 Jul 2024 00:00:00 +0000

I inherited a Go service where the primary domain object was a struct with 47 fields. Some were database columns, some were computed from other fields, some were HTTP response projections, some were used only during a specific workflow stage, and a handful were there because someone once needed a flag and adding a field to the God struct was the path of least resistance. The struct was everywhere — passed between functions, serialized to JSON, written to the database, and used as a GraphQL response type. Every change to it rippled through the entire codebase.

Lesson 2: Spotting Over-Abstraction — When your abstraction is the problem

Wed, 24 Jul 2024 00:00:00 +0000

There’s a version of Go code I see in almost every codebase that’s been touched by developers who came from Java or C# — it’s covered in interfaces, repositories, factories, and service layers that all wrap exactly one concrete implementation. No tests mock these interfaces. No second implementation exists. The abstraction is doing nothing except adding indirection. I’ve written code like this myself, and the tell is always the same: when something breaks, I have to jump through five files to understand what happens when I call CreateUser.

Lesson 1: Interface Everywhere Syndrome — Not every dependency needs an interface

Tue, 18 Jun 2024 00:00:00 +0000

When I came to Go from a Java background, I brought some habits with me that made my code worse, not better. The most persistent one was defining an interface for every dependency, regardless of whether there was any realistic chance of substituting an alternative implementation. I wrote UserRepositoryInterface, EmailSenderInterface, LoggerInterface — an entire shadow type system that mirrored every concrete type in the codebase. Every file had a corresponding interface file. The codebase was twice as large as it needed to be and no easier to test.

Lesson 1: Refactoring Go Code Safely — Change structure without changing behavior

Sun, 16 Jun 2024 00:00:00 +0000

Refactoring is the one activity that makes codebases better without adding features — and it’s also the activity most likely to introduce bugs if done carelessly. I learned this the hard way on a payments service where I renamed a function, ran the tests, saw green, deployed, and watched a webhook handler silently stop processing because it had been calling the old function name through a string-based registry I hadn’t touched. The tests were green because the old function still existed — I just hadn’t deleted it yet. The refactor was correct; the process was not.