I'm at the start of my career as a software engineer but it seems to me a good rule for refactoring is that it should only ever be done if the advantage can be evaluated in the form of concrete new features being easier to implement. If you refactor the code so that existing features would've felt nicer to implement, or are nicer to read, you've already played yourself, because maybe you get a high of ecstasy because the code that was ugly before is now clean, but as soon as the next feature comes around that you didn't anticipate, it was all for naught, and you're writing ugly code again.
But sometimes you’re working in a codebase which will probably outlive you. And in that case it often makes sense to think of your code base as a garden that you tend. Spending effort making tending the garden delightful will almost always pay off given enough time. And here I’m thinking about things like improving the build process to speed up compilation, adding tracing to make debugging easier, refactoring, documenting the core design and philosophy, and so on.
You can’t make Google chrome, the Linux kernel, llvm, or other projects like that by taking dirty shortcuts every time you add a new feature. If you do, you’ll end up with a buggy, unmaintainable mess that is impossible to change without introducing new problems. This isn't just theoretical - look up the story of Toyota's brake problem a few years ago. I've also heard some grizzly stories about software practices at Boeing and Oracle.
Good cooks clean their kitchens. Soldiers maintain their equipment. And efficient programmers keep tidy codebases.
I tend to see little discussion about long term value. "Long term value" includes "making it less expensive to add features." At my current company, we would run in circles chasing the same bugs because of spaghetti code plus competing business requirements. The answer to "why do new features take so long?" was fairly straightforward.
We were able to argue for a rewrite partially on the grounds of the speed of future enhancements. During the rewrite, it has been amazing to several team members (juniors, management) at how easy it is to track changing requirements when there's good infrastructure and when solutions are kept simple.
This is so rare, it's not worth thinking about. Code lasts a decade or two before it's been completely rewritten or replaced. After 30 years, the oldest code that I ever touched exists in very few places (2 that I know of).
> Spending effort making tending the garden delightful will almost always pay off given enough time.
What constitutes "good practice" is ever-changing and it doesn't add business value. You work within the constraints of the time and move on. The people who do this find themselves in the best position, career-wise. Paying some small attention to maintenance helps you move up and on to bigger projects and responsibility. Like all things, pursue a middle ground of philosophy. ie You can fiddle with code forever trying to make it "better". More extensible, more maintainable, more clear, more more more.
Arguing over future cases (premature planning) is the most common sin. Planning for everything to be reused is not being efficient. Regardless, you have biases that inform what you think is "better" and how software will be used, which future you (and other developers) will note share.
There's definitely a scale between "unmaintainable mess" and "architecture astronomy" where both extremes are pathological.
I've seen plenty of unmaintainable messes in my time - particularly from average teams who are lacking in good technical leadership. You see this sort of thing all the time in consulting, and in software teams at non-software companies. (Eg, in the airline industry). There's a reason why Martin Fowler talks a lot about software craftsmanship - because at places like Thoughtworks they could often use more of that sort of thinking.
I've also seen plenty of overengineered messes too. Most smart college students (myself included) seem to need to go through this at some early point in our careers, where we really spread our wings and discover first hand why writing thousands of java classes is a terrible idea. (Or whatever the poison of the day is). If all your abstraction does is move your food (business logic / algorithms) around the plate, or -worse- hide it, then your abstraction is making the code worse.
I have no idea which sin is more common. I think it really depends on what sort of engineers you spend time with. Google definitely suffers from the second kind of problem much more than the first - to the point where google (hilariously) often outsources making actual websites to external consulting companies, because their own software practices are too expensive to implement.
Does your team need more long term thinking or more short term thinking? Its impossible to answer without reference to your actual team, your existing practices, and what you're trying to deliver. A weekend game jam should be scrappy, and the code for the space shuttle should be written carefully. Neither approach is objectively good or bad; there's just different tradeoffs appropriate for different kinds of project. The best senior programmers can switch style & philosophy based on whats needed for the task sitting right in front of them.
Couldn't help but remember the comments in the Apollo-11 source code saying "TEMPORARY, I HOPE HOPE HOPE".
https://github.com/chrislgarry/Apollo-11/blob/a13539c7c5c482...
This is so rare, it's not worth thinking about.
It might be rare in the sense of code that will be around after you're dead. But it's probably not rare in the sense of code that will be around after you've left the company.I don’t think that the answer is for engineers to just “suck it up” and wait until there aren’t pressing feature demands (which usually never happens). But instead, we should spend time reading the code our coworkers and past employees have written to understand the design and philosophy behind it.
If the design of something you’re working on isn’t good by your standards, your productivity will still suffer if you leave it how it is. Especially if you have good taste. The feeling of deep authorship - like, “this is my garden and I’m proud of it” is something worth cultivating even if you only care about output.
I can close way more tickets in a day if I feel at home & in control with a codebase. And that’s something that matters to business as well as the engineers on the ground.
* how quickly can you answer questions about business metrics?
* how easy is it to identify that bugs are occurring?
* how long does it take to figure out what to fix when it's broken?
* how much change is involved in fixes (e.g. does a PR fixing an issue touch like 25 files or does it touch just a few files?
* how quickly can new employees come up to speed on the code and alter it confidently?
* how easy is it to add new features?
Now, these things are hard or take time to measure, but those are qualities I look for when determining if a codebase is good.
You need to measure these things objectively. There are several ways to estimate technical debt, like asking system owners how long their teams would take to bring their code up to a list of standards. The time estimate alone is an excellent tool to measure the scope or remediation cost. But there are also several more aspects to technical debt: transmissibility (how likely it is to spread), remediation competencies (does the team have the skills to remediate it), maintainability (how much does it cost to maintain this case of tech debt over a month or a year), attributed bug count (how many bugs are linked to this instance of debt), and so on.
Refactoring code just because someone has complaints is an indolent and unsurprisingly ineffective way of maintaining it. As you say, opinions about how code should be written are a dime a dozen. The shortcomings of a particular system need to be meaningful and clear before they can be assertively fixed. They can be generalized, like "this code doesn't follow patterns that would optimize it" or "this code has had too many hotfixes and is now causing many bugs", or precise, like "cache misses here impact systems A, B, and C severely". But they still need to be clear and business-oriented. Then tech debt repayments can be very effective. I have seen bugs attributed to a system go down by 90%+ after a short refactor when it was carried out effectively.
Investing into systems that prevent tech debt in the first place can also be effective, but it likewise has to be done in a measured and targeted way. If teams tend to make mistake X, then you can often deploy code analysis or submission tools to identify that mistake and reject such code. Over a project's lifetime, you may write hundreds of such code validation tests, but in teams of 100+ people, they can prevent a tremendous amount of work resulting from tech debt.
In short, it is a mistake to dismiss the tech debt problem when one has not put in the effort to tame it or has gone about taming it in a lazy, wishy-washy way. If the team has particular code quality standards illuminating tech debt and allowing the coders to target it clearly, it can be remediated effectively.
There are objective parameters like: tests coverage, how many bugs you have (or were fixed) on from the static analysis, presence of periodic or constant fuzzing, portability.
So, if you've already shipped a feature and need to make some kind of change, you can't do so with any confidence. Implementing unit tests to validate you're not breaking existing functionality is impossible, so you need to refactor, which introduces extra risk.
Are you going to tell me that this kind of tech debt doesn't affect my time to fix the bug? I could have done it once, now I have to hunt for 5+ instances of it. Am I just complaining or did doing the original development in a lazy way directly impact my time to complete the task?
I could have recorded the exact amount between the original bug fix and finally fixing the last instance of the bug to quantify how much time lazy coding cost me. It may have taken the same amount of time to write the original pages with an extendable component that only has one copy and takes arguments to create all the variations we need. But in the end we'd have fewer lines of code to maintain in the future and that's also an objective metric.
Simple duplication is probably the least bad form of tech debt I can imagine.
the real horror is they have slightly different version since they already had other changes done to them, and I have to understand whether I should merge the functionality, keep it different, etc.
when I have multiple callers it's going to be the same unless you pass in an argument, so that change is self-documenting since it signifies intent
For your scenario, I completely agree that the decision to not share code lead to you spending more time. We can be objective about time spent for specific scenario A with codebase B, but we cannot enumerate all scenarios and all codebases and so it's quite hard to ask what's the expected value for "damage done" by a particular style of programming.
Instead of copy pasting from page A and changing it, you should have a function that does the same things from page A and B, and then combining that partial result into the different pages in the way that you want. The function that does the same task for the pages can then be fixed for both pages if it has a bug in it.
If you copy/paste then inevitably the person working on it will forget to find and fix one of the versions.
But even if you end up spending a little more time to prevent code duplication than just copy/pasting, it STILL yields benefits in the lower maintenance cost since people will spend less time reading and understanding the code. Your codebase will have fewer lines of actual code, which is a win by itself, which you can quantify.
You won't be able to measure the time each person will waste re-reading identical code to make sure it's actually identical (or worse, trying to see WHY it's not identical), but it's always a cost if you're working with this code. The only reason not to touch it if it's already perfect and won't be changed. But usually I will start on this refactor when I do have a requirement (it already has a bug, or I need to change functionality)
The bonus of doing things like this is that if you are constantly changing your code then it becomes battle hardened to accept change. This gives you better ability to keep up with the changing demands of both customers and technology.
There are some things that are not just annoying to deal with, but actively impede development or encourage further hackery to make them manageable. Those things need to be fixed at some point, or there will be a real cost.
The problem as I see it: companies prefer the inexperienced devs because they're less expensive, and as a result, their inexperience leaves them frustrated with code that they "don't like." They then attempt to sell management on a rewrite on these grounds.
The team can only deliver features that customers want, on the schedule the business wants, if the underlying infrastructure of the code allows it. If the code infrastructure forces me to spend too much time implementing features, and feature requests continue pouring in, then there will never be time to refactor because there will always be "pressing feature demands."
At the time of change, its obvious you're making the code shittier. That function? It doesn't do what it says anymore. That other function? Just a few more boolean variables. Hey, we don't need to refactor, we can just make negative numbers mean one thing, and positive ones mean another! Death by a thousand cuts.
This is also the best time to refactor. You skip the whole "I don't like the way the code looks" bullshit. The codebase doesn't support your feature? Make it support your feature, then code your feature.
And you know what else? You are only changing code you're touching. Refactoring code you don't need to otherwise touch is a waste of time.
But yeah, if you parachute in 6 months later to look for a refactor, its gonna be all gravy. How much shittier your code is just a distant memory. Get on that next feature - just another flag, just another lying variable - in hindsight, it's all subjective anyways.
If the answer is “No”, it can be difficult for others to understand. Reworking that code to follow our architecture generally makes it easier for us all to follow.
One might need to not follow the architecture because it doesn’t handle something new to the app. When that happens, we try, first, to update the architecture to be able to handle the requirement and then implement the feature. But if that isn’t possible, we plan to clean up the debt as soon as we can after shipping.
Overall, it has worked remarkably well for our team and has led to what I consider the “cleanest” code base I have ever worked on. But it is dependent upon us having a shared understanding of how we implement features.
Doesn't matter what the code looks like, as long as the customers
are happy.
Can you imagine if other industries had this same attitude?"It doesn't matter what the warehouse looks like, as long as we ship on time, and the customers are happy."
At one level that's true, but at another level, it does matter what your warehouse looks like, because a neat and tidy warehouse is what allows you to ship on time. A warehouse that's filthy and disorganized is one which loses orders, ships the wrong products. Similarly a disorganized codebase with poor abstractions isn't bad because it's unpleasant to work in. It's bad because when a dev ships a feature, they have little or no confidence that they've done so without breaking two or three other features and causing customer dissatisfaction in the process.
Most programmers imagine other industries to be better because they only see the customer facing parts, but that is like judging the state of a codebase by how nice the landing page is styled. Penny-pinching managers exist in all industries.
[1]: https://www.joelonsoftware.com/2005/05/11/making-wrong-code-...
Yes, but there is a time dimension to "code works". It should work tomorrow when a new OS comes out, and it should work when a library is updated because of a vulnerability, and it should still work when a new feature is added, and it should still work with a 100x more users.
The only way to make sure code still "works" in these situations is to continuously keep modifying it. And here the technical debt comes into play.
The ability to reason about it or even measure it might be subjective, in the sense that most developers aren't really good at articulating quality. Also, developers often confuse familiarity and quality, or to be a bit more generous: are unable to accurately assess quality of unfamiliar technology.
Furthermore, there is also a widespread misunderstanding that if you can't 100% prove something beyond a shred of doubt, that any position is as arbitrary as a favorite color and any reasoning a waste of time.
> Doesn't matter what the code looks like, as long as the customers are happy.
Customers being happy or not is exactly the problem of Code Quality. When a system breaks down over time due to a pervasive neglect of quality, the customers won't be happy. In practice this is happening slowly over time. Your lead time increases, there will be more bugs and changes will cause more problems that are increasingly hard to overcome. It can also come as a collapse, for example a huge outage, data loss or security incident. This can kill your business.
Quality is not something done for developers sake, it is about the ability of making customer happy over time rather than just now. That is the ultimate justification, which isn't subjective, and the source of legitimacy of any time spent on refactoring at all.
If it is not ultimately rooted in solving a business problem, then it is not a quality improvement at all. And yes, sometimes developers try to masquerade personal taste as quality (refactor to something I know or like), and in these cases the outcome often isn't an improvement at all. In fact, it is often a regression. But that doesn't mean quality improvements aren't real or beneficial.
My problem with the concept of technical debt is that "code quality" is subjective, and more often than not it translates to "I don't like the structure of this code because I didn't write it". What matters to the business is that the code works. The owners of the business do not care if the developers enjoy working with the code or if they find it to be well written.
I hear all the time that bad code slows down development, increases bugs, etc. And that can be true in a number of cases. But most of the time it's just complaining. If a developer takes the time to re-factor the code base, it's very likely that whoever takes over from them in a few years will have the same complaints about technical debt and want to re-factor all over again.
The best way to ensure everyone's job and increase compensation is to deliver features that customers really want. Doesn't matter what the code looks like, as long as the customers are happy. Re-factoring is important to developers and to maintaining an organization. But it can wait until there aren't pressing feature demands.