Code quality: a concern for businesses, bottom lines, and empathetic programmers (stackoverflow.blog)

You provided business value ASAP, and, if tech debt was ignored in the beginning, it's probably because there were good reasons to do so.

Your job is to architect a good enough system based on the requirements you have and the assumptions that you make. It might help to document these using something like ADR, but this depends on your context. I found out about a decade ago that documenting these assumptions and estimating impact/risk and potential mitigations might help to motivate your choices.

In hindsight it's always easy to tell why an existing architecture was the wrong choice, but this is a fallacy, as architecture is based on a snapshot, and you have to find a delicate balance between changing architecture and providing business value all the time.

I usually advise against big rewrites, in my own code I try to aim for "making parts easily disposable or replaceable"; if the mess is abstracted away it doesn't seem to matter in 90% of the cases. In the 10% where it does matter, you'll end up refactoring anyway because it's probably your core domain and your insights and learning are evolving faster there, and you will inflict a lot of pain on yourself if you don't respect proper development practices in those parts.

It's virtually impossible to rewrite a large scale application where the only documentation is the code, especially if the code is bad enough to warrant a rewrite. You will break things, lose features, potentially corrupt data. Total rewrites of unspecified, untestable, poorly understood systems should be the last resort.

That said, the system was still running with customers using it 2 and a half years later, which is a very strong signal that it didn't need a rewrite after all. It sounds like you got it right - refactor as you go is usually the best way out of a bad codebase.

Quality code where you can get away with it not being is a fragile thing (in the fragile/anti fragile) sense.

I wonder if the hill to die on is getting a good architecture that minimises the impact of bad code not as bad.

We cannot change ANYTHING. ANYWHERE with our current stack, due to years of product micro-managing engineering and never having room to re-build or improve things. Also just bad practice from inexperienced engineers with 0 leadership.

We tried to do the "microservice" thing but we never ACTUALLY got the bandwidth in our sprints to do all the work that is needed, and product never backed us up to deprecate old APIs that were too tightly coupled with a ton of other functionality to adequately refactor( Also the code quality was so poor it is hard to reverse-engineer the API ). So we have the new APIs sitting dark.

Here is another fun knock-on effect: Everyone who joins quits as soon as possible, because their job is nothing but fucking around with shitty code written by someone half-way to Tahiti by now.

Heck: I have had to convince myself to stay several times now[0]. I ask myself: Is what I am doing worth my time? Am I growing? What am I going to tell my next employer? Will saying: "I spent a year nursing a dying monolith built on a mountain of bad practices" get me my next job? I hope I can help heal this place and get it to a better position, but better people than I have failed.

0: I had a run of crappy gigs and I don't want to switch since this is tolerable so far.

> Of course, this moreso applies to SaaS where your product lives forever.

The thing is, though, SaaS products don't live forever. In fact, they have ridiculously short half life :). Sometimes it's the effect of the problems of code quality (in which case the company dies prematurely, or the product gets rewritten in a new tech stack). But often enough, it's the cause.

Plenty of startups are eyeing for an exit from day one. They fly their "rocket ship" the Kerbal way: building the vehicle out of old oil tanks welded together and filled with rocket fuel, and having a bunch of green men on the outside desperately plugging every leak as the rocket tries to break out of the atmosphere, praying it'll get to the Moon before it explodes. There's a top-down pressure to move fast, instead of worrying about code quality, because there's only one goal: exit or bust.

Businesses run on cash flow like blood. Once the cash stops, it dies right then and there. It doesn’t matter if a better design will only take a few more months if you can’t make it to tomorrow.

I am currently in a similar situation but it is all scripts on an industrial data historian intertwined with DB updates.

When the previous hire gave notice he had 2 weeks to document what took many people more than 5 years of effort to piece together.

I won't call this hell, but at least my manager and boss have very tempered expectations.

Edit: I'll be sending this article out to my co-workers in the morning with some snippets.

From management and customer point of view, "it works" is the only quality measure.

No one cares about opening the box and the less one knows about how the sausage is made the better.

I consider focus on code quality everywhere a form of premature optimization. Only focus on quality where it hurts... But if it hurts (f.e. you had to change it 3 times and it got messier each time), be very disciplined about refactoring to a better model: whiteboard, brainstorm etc and don't start refactoring until you found a better model.

No, it's much harder for technical leadership. Technical leadership operates on opinions, fads, cargo-cult, etc., like you said.

Non-technical leadership can always fall back on business fundamentals.

https://www.pri.org/stories/2012-08-25/amateur-restoration-b...

It's ironic to me that the "Hammer Factory Factory Factory" post was recently doing the rounds again.

I have recently been working with a client whose "senior" dev swallowed some books with opinions on "quality" wholesale and uncritically.

Thus in the simplest project, implementations that could literally be a lambda function (on receive message, write row into DB) are a festival of multiple tiers of objects, mappers, mediators, IoC frameworks, wrappers, Nuget packages, etc., etc.

Everything is in multiple projects. Simple constants (like: API routes - '/api/foo/bar') are indirected into files containing those strings, so there's a huge cognitive overhead and much clicking around to make sense of it. God help you if you don't use an IDE.

This isn't quality. It's the antithesis of quality. Devs have to understand a whole load of abstractions just to get simple things done. But the author is proud of his tower of 'best practice' - blissfully unaware that adding the simplest feature is now hundreds of lines of code, where one would suffice. This is burning through, literally, thousands of euros of dev time.

Actually there is: Tech debt materializes in all measurable metrics of the project. Project Deadlines continuously are missed and the time at which they overshoot increases.

A project needs "exponential" people. The quit rate among the developers constantly increases, with experienced devs quitting first.

All these signals should allow actually easily to create a metric for code-quality. Its a signal that bounces from the code through the system to you.

We have ways of computating the original value after it has bounced through the develop teams system.

https://en.wikipedia.org/wiki/Convolution

The problem is rather- nobody wants to know how much debt they own, or to speak bluntly, whether the situation one is in, is actually a tech-debt bankruptcy.

I have to disagree with you on this point (and your third point)

I've seen so many examples where developers DID improve Code quality (CQ) from of the numerous automated/personal quality checks available. (Though what follows is from a Frontend dev perspective)

- CI is CQ

- Code Review is CQ

- IDE w/ Linters is a form of CQ

- `tsserver` is an real-time type CQ

- Immutability is a passive CQ

Idk, maybe Frontend-space is a world away from what you're working with every day, but CQ in my domain has both technological and cultural tools available before code ever reaches the end-user.

> So for non-technical leadership, it is hard to know if "extra time" spent on code quality actually improves anything or is a waste of time and money.

This is really interesting to me as a problem statement: how can devs unfold/make known the value of CQ as a critical function in this math? (I don't have an answer, but I think about it a lot). What are we not sharing – or, worse, what methods/language/etc. are we using that don't fully translate between teams?

I feel it's the job of the org to be able to identify this kind of bottleneck. What position within an org is responsible for explicating the properties of this kind of issue? (Again, I don't know)

Code quality is your new feature rollout average time.

If it's a steep rising curve it is abysmal, if it's mostly flat you have an excellent team.

If it was flat but exponentially grew after you went on a hire spree, you know where to look at.

Management DO NOT UNDERSTAND code quality.

Management DO NOT UNDERSTAND how to measure developer productivity.

In my 16years of doing "this" no manger has ever had the background nessesary to understand software.

And "technical managers" seem to bee made up entirety of mechanical engineers that can not comprehend anything but waterfall.

More often than not I see "code quality" as an excuse for being lazy or generic blanket argument that you cannot refute because "code quality".

While it's indeed hard to get objective measurements looking at the codebase alone, telling a manager things like

"look, this is going to take 5x the amount of time it should because the current code is a complete mess so I have to be extra careful not to break things and it takes way longer than it should to figure out where I have to put the new feature in order to mimimize the amount of extra chaos created"

or

"I cannot do anything sensibly without refactoring this first but it will pay off in the next couple of months and years to follow"

should make it pretty clear the quality isn't where it should be. If management doesn't grasp that, or doesn't want to hear it, then management quality is probably at the same level as the code's. I know I'm in a position not every developer is, but when needed I ask and get extra time for things like this. Because I've seen what happens when you try to build a trainwreck on top of existing ones: that stuff is exponential, at least.

> - Code quality is quite subjective and the field is driven by opinions and fads.

Agree. In almost every team I have been part of, when discussing code quality there was almost never consensus regarding what's good and bad.

Besides, in almost every company I have worked for, modules (or products) were usually refactored after 3 years or so (as in: the code that deals with retrieving data from the DB remains almost intact, but everything else is moved out to its own repository: the frontend as microfrontend and a new in-between layer (call it a proxy or "backend for frontend"))... so there was never a huge motivation to write quality code, just to write "good enough" code.

From a business perspective, investing in architecture quality buys a lot more optionality than investing in code quality, and so prioritizing the former is almost always the right decision.

I think a big part of this is the tech industries failure to grasp the value of experience. Experience teaches you to pick out the fads from the fashions and the values of various opinions. It helps develop your code smell and your ability to discern the quality of a work. All other trades value experience and trust it to help measure these things. If you wanted to judge the quality of work done by a junior plumber you'd bring in a master plumber to evaluate it.

I'd add that for doing projects for fun or POC, it still pays to pull in something like TypeScript if it's a JavaScript project, even if you're not overly fussy with the typings -- the benefits will outweigh the drawbacks, and you never know when a POC will turn into something bigger.

Choose some sensible tools with a good balance of structure and pragmatism and write some damn code. Keep it modular. Don't spend weeks obsessing and agonising.

I'd argue code quality matters a lot more than in a company with already a lot of inertia, for which a week or two of delays on a new feature matters a lot less.

You better hurry up too, because you have a problem if you don’t finish before your debt catched up to you.

Some things that can help move towards higher quality code: - avoid duplicated code - especially when it's similar but subtly different - variable names that mean something useful - lower code nesting - shorter functions - fewer parameters

Many of these things are focused on improving how understandable / maintainable the code is.

But, as for novels, there aren't just rules you can follow blindly.

Perhaps this helps: https://garywoodfine.com/what-is-clean-code/

Closed source strongly correlates with business, which strongly correlates with paid employees, competition, investment - meaning time pressure. Open source strongly correlates with volunteers working on free solutions in search of adoption - meaning little time pressure.

Less experienced technical managers may resort to a similar wording as the one you just mentioned to prevent that dev to refactor something without really having a good idea how it should be in the first place.

Again, not saying that's what's going on in your example, but I've seen this more than just once.

> require the programmer to understand and remember extra layers of context

in

    sum(i for i in texts)

    for i in texts:
        # A page of code without i in it.
        

To be fair most of that time they were optimising for writing in pen/chalk, where shorter names save a lot of work.

    const containerRatio = (containerWidth / containerHeight);
    const targetRatio = (targetWidth / targetHeight);
    const useVertical = (containerRatio > targetRatio);

    const scaleFactor = (isVertical
      ? (containerHeight / targetHeight)
      : (containerWidth / targetWidth)
    );

    const scaledWidth   = targetWidth * scaleFactor;
    const scaledHeight  = targetHeight * scaleFactor;

    let x0 = 0;
    if (isVertical) {
      x0 = 0.5 * (containerWidth - scaledWidth);
      x0 /= (1 - scaleFactor);
    }

    let y0 = 0;
    if (!isVertical) {
      y0 = 0.5 * (containerHeight - scaledHeight);
      y0 /= (1 - scaleFactor);
    }

    return [[x0, y0], scalingFactor];

    const r  = (w / h);
    const tr  = (tw / th);
    const m   = (r > tr ? (h / th) : (w / tw));
    const o = [0, 0];
    if (r > tr) {
      o[0] = (0.5 * (w - tw * m)) / (1 - m);
    } else {
      o[1] = (0.5 * (h - th * m)) / (1 - m);
    }
    return [o, m];

If there was a problem with the second example, I'd have to more or less rewrite the logic myself into the first form in order to figure out what it was doing.

There's a balance; too much tech debt and the code isn't profitable. But too little tech debt is not profitable either.

This is changing. For example, Banks are slowly realising that they are delivering all their services via technology. A serious outage of banking infrastructure can ruin lives, see for example the TSB debacle in the UK which even forced the then CEO out.

Personally I think quality is really hard, we don't do it nearly enough. And it will be increasingly important.

There are firms who ship outstanding UX and tech. They will eat everyone's lunch if others don't manage to catch up. Reliability, consistency, responsiveness, performance... These things add up, because users apparently really like tools that are polished, just work reliably and perform well.

So many horror stories have been piling up about just plain bad software and so much just doesn't work as it is supposed to work. There will be a turning point where we can't keep only throwing things at the wall and see what sticks.

I think this kind of stuff will become one of the primary distinguishing features for products and services as expectations go up. People are getting tired of software that doesn't work and countless apps that crave for user attention and needs constant fixing. It's too expensive and useless. Useful, really well made stuff is going to dominate.

That's not what you're criticizing directly here. But in my opinion this goes all the way down. Broken window theory and all that. Framing it as "developer productivity" seems wrong to me and perhaps reveals where the issues are. That's not what quality is primarily about I don't think.

We're in midst of a revolution, but at some point we need to grow up, take more responsibility for what we make and be _actually sure_ that we can do that with confidence.

And now look at the few firms at the top who broke the 1T barrier. All tech focused, almost all lead by engineering and engineers at the top.

I chose my bank based on the quality of its phone app. I choose my hotels based on their ease of booking. We picked my wife's car based on its ability to connect to our phones. I've switched brokers because their web interface was so buggy. And on and on.

If your employer can't provide a good quality interface then it won't be getting any of my business.

Talking about switching CSS preprocessors is a red herring when so much enterprise software is shit.

DDD = Domain-driven design

CQRS = Command and Query Responsibility Segregation

If you haven't read it: I think you'd like the book A Philosophy of Software Design by Ousterhout. It has a very strong notion of what you said and discusses this in a down to earth kind of manner. Very few terms were invented in that book, but it showcases a collection of sensible heuristics and actionable advice.

Also, what is the category/term called for those type of pain points? It's like those typical enterprise-y, sad but true, jaded senior tropes.

Like this question:

> How to represent a form from an object that isn’t backed by a row in the table?

I don't know how to describe it exactly, but it's like a question that gives off a strong signal of someone operating at a high level in an enterprise context.

I'm genuinely curious on the ways people solved those types of questions.