Don't refactor the code
Paweł Świątkowski

Paweł Świątkowski @katafrakt

Location:
Wrocław, Poland
Joined:
Mar 30, 2018

Don't refactor the code

Publish Date: Jun 13 '24
325 30

This is a piece of advice someone gave me a long time ago. Unfortunately, I don't really remember who, so I cannot properly attribute (although chances are they heard it somewhere too). But I decided to re-share this.

What is refactoring? I'm sure we can find multitude of definitions. But with modern software development process it often becomes synonymous with any kind of code changes that do not add, modify or remove features. In other words, a non-product work. In effect it often becomes a blurry term and cause of tension between product stakeholders and the dev team.

Who among us did not hear that on a status meeting: "Yesterday I spent most time refactoring the code around X"? I know I did. No less, I probably said a phrase like that more than once. What does this mean? What did you really do? This is hidden behind "I refactored" term. "I did an important technical work you would not understand" is another way of framing that.

And this is exactly the problem with "refactoring the code". In many cases it means doing a really important work, but it's indistinguishable from almost-slacking-off, like renaming variables for no apparent reason.

And this is what I mean by "don't refactor the code": use different words when talking about things you did, are doing or plan to do. Don't "refactor". Instead try these:

  • I made the code more performant (identified N+1, found inefficient processing of a large amount of data)

  • I made the code more open to change (mostly should be justified by prediction that we will be changing this area more often now)

  • I made the code more defensive (failing early and with a clear message if run with incorrect arguments - because other teams are using it incorrectly and it leads to a subtle bugs)

  • I added the tests for an untested area (good rationale: because it failed few times recently; bad rationale: to increase our arbitrary code coverage metrics)

  • I added more logging / instrumentation (so we can understand better what is going on)

  • I change the code to meet our new style guide (because we will change it often)

Communicating like this is not only makes it easier for others to understand what was changed, but also helps you decide if the change you plan to make really makes a difference. Not being able to hide behind an umbrella "refactoring" term also helps to keep the changes more focused and easier to review for your colleagues.

Comments 30 total

  • Eckehard
    EckehardJun 14, 2024

    If you tell somebody, you need time to clean up your room, isn´t this enough? Often it is not too interesting if you need the time to remove all the empty pizza boxes from your bed or if you are cleaning the windows.

    • Paweł Świątkowski
      Paweł ŚwiątkowskiJun 14, 2024

      It is, if you are the only person using the room. Thing is, you are not.

    • Yutamago
      YutamagoJun 15, 2024

      If it's a shared room, the other users might ask you why you cleaned up the room. Why you moved the closets to a different corner and why you relabeled the drawers. It was perfectly fine before.

  • david duymelinck
    david duymelinckJun 14, 2024

    I agree with you with the part that refactoring means just pushing code around without a benefit.

    The one case you missed, which is a cause that happens most often, is an update of the language/framework/solution. Of course you need to decide the update is worth the work that is needed for the refactoring.

    I think refactoring isn't a term that should retire. Only do refactoring that makes things better.

  • Andy The Web Dev Queen
    Andy The Web Dev QueenJun 14, 2024

    The communication is always very important, especially when you deliver the product directly to the client. The client usually wants to know what exactly you did with his money and the benefits of such change. It also increases your value in his eyes when you can talk about reasons with confidence and have data/knowledge you can share to prove them.

  • Craig McNicholas
    Craig McNicholasJun 14, 2024

    I agree, just saying "refactoring" is like saying I'm "documenting" or "compiling". Compiling or documenting what exactly?

    It's fine to use the word refactoring but as you state it needs context, what is the goal trying to be achieved? Everything from better readability in a highly shared codebase through to renaming to follow conventions etc. are all valid reasons but you gotta be able to back up why else it's just busy work.

  • John McCabe
    John McCabeJun 14, 2024

    Basically, all you're saying is never claim to be just refactoring code. The only reason you should be refactoring anything is because there's a clear, probably documented (e.g. bug report, feature request - including improvement) need for it. If you're daft enough to suggest that all you were did was refactoring, rather than "progressing with task x, which needed some existing code to be refactored", then you need to think harder about what your actual end goal is. This is what you're saying; the headline of this article is, however, provocative and untrue.

    • Seisgasse House1
      Seisgasse House1Jun 15, 2024

      the title is stupid tbh. what the heck with these titles.

      • Bernard Igiri
        Bernard IgiriJun 15, 2024

        If no one clicks then you're writing for nothing.

        • Seisgasse House1
          Seisgasse House1Jun 15, 2024

          Then stop writing. Software Engineer is a science not a melodrama.

          • tacodes
            tacodesJun 19, 2024

            When you fix human nature, Seisgasse, you let us know! Until then article titles will be click-baity. Waiting on you!

  • Nicholas Rios
    Nicholas RiosJun 15, 2024

    Depends on your audience. PMs don't know the difference.

    • Paweł Świątkowski
      Paweł ŚwiątkowskiJun 15, 2024

      They often do.
      But even if we assume they don't, it to no one's gain if they start associating refactoring with slacking off.

  • Mr_Green
    Mr_GreenJun 15, 2024

    Yes it makes sense to be precise with the team instead of vague. This gives context to the team and room for quick feedbacks.

    Also imo, refactoring must be a team effort not one guys opinions induced on others. For example, renaming of variables to readable names must be a team agreed Dev practices or atleast a quickly consented one. At the end the code must be as if one guy wrote it but not visibly bunch of devs with different opinions/approaches.

  • Marcos Silva
    Marcos SilvaJun 15, 2024

    It always depends...

  • Mirek Sedzinski
    Mirek SedzinskiJun 15, 2024

    Most code refactoring should happen as a side activity, and you don't have to even mention about it (except maybe a comment in PR).

    Very basic example: i worked on feature X and at the same time i found a typo in a variable name and fixed it. Or i added one test that i thought was missing.

    If you plan to work 1 day on improving a performance of something (your example) then you'd better discuss it in advance, agree and plan.

  • Claudio Stella
    Claudio StellaJun 15, 2024

    I would just add, don't refactor if there are not enough tests that prove that everything is working correctly. And if there are not tests write them first. So don't , don't refactor for the sake of it.

  • J Karelins
    J KarelinsJun 15, 2024

    ..., until it works 😅

  • Rense Bakker
    Rense BakkerJun 15, 2024

    Yes and no. Sometimes it's not that interesting to go into details about what you refactored exactly. For example if you renamed some variables, that's not super useful to know. People who are interested can look at your PR and ask for clarification if they want more explanation. The reason why it needed refactoring could be important if the bad code could have been prevented beforehand.

  • Paweł Kubik
    Paweł KubikJun 15, 2024

    I agree. You need to stay focused on the real problems and proper reporting is an good way to promote that. It's not as much about reporting itself as about making sure that each contributor thinks about your goals. W sometimes find ourselves replacing if-else blocks with cleaner polymorphic interfaces, that we need to scrap few weeks later when they don't match some new features. Code quality can be easily misjudged when taken out of context.

    That said, I think the sentiment of the title is a bit misleading and potentially harmful. Thinking how to report your work has a lot of benefits, but maintaining proper refactoring culture is way more important. I'd put quotes around "refactoring" in the title to better match your point.

  • ss ss
    ss ssJun 15, 2024

    You are funny. Do not refactor the code. How about do not make bullshit content, if nothing to say

  • Jakub Zalas
    Jakub ZalasJun 15, 2024

    I refactor constantly with no mercy as part of my every day work. There’s no need to mention it at all as it’s so common. Just like writing tests. I refactor to make it easier to add a feature, to increase my understanding, to improve readability, etc. Whatever the reason, it’s part of every task I work on. It’s never a separate piece of work.

    Having said that, I’m very interested in eventually coming up with a system that Greg Young spoke about in „The art of destroying software”. System so modular that we rewrite its modules instead of refactoring.

  • Bruce McKenzie
    Bruce McKenzieJun 15, 2024

    I'm ok with the provocative title.

    You are largely correct.

    My only quibble is that i don't think of your reasons as truly refactoring. Improving performance? Not requiring. Should be product-driven. Testability? Should be qa-driven either specifically or in support of organizations goals.

    Refactoring (to me) if changing the code without changing the functionality (including most non-functional requirements).

    I think there are two reasons to refactor: "you have a change you are working towards and the code is not structured to make it clean", and "you are reducing technical debt" .

    The former? You're writing on the change. You shouldn't check in those changes if you don't check in the feature.

    What is technical debt? Things we now know we should have done differently. (Insert longer and more precise explanation)

    I don't believe in "making it more open to GENERAL change" because that is not relevant to prodic needs. Is relevant as to our guess about product needs, and as such can be wrong, or a poor allocation of resources.

    Keep up the clear writing!

  • Mahmoud Kanbar
    Mahmoud KanbarJun 16, 2024

    The title is so catchy, and give you a big rush to read the article, specially because you want to argue with the writer. "The content is the contrast of the title".

    Very nice point of view, And I totally agree with you.

    Thanks.

  • padrigikna
    padrigiknaJun 16, 2024

    When comparing OCD personality disorder vs OCD, it's important to note that OCD is a specific disorder involving obsessions and compulsions, while the term "OCD personality disorder" is often used informally to describe OCPD. This can lead to confusion, as the two conditions require different treatment strategies. OCD typically responds well to a combination of cognitive-behavioral therapy and medication, whereas OCPD may benefit from therapy focused on improving flexibility and reducing perfectionistic tendencies. Clear differentiation between the two ensures that individuals receive the most effective care.

  • padrigikna
    padrigiknaJun 16, 2024

    When you choose a bed from Dream Gold Beds, you're investing in quality. Our single bed with mattress sets are crafted to provide maximum comfort, ensuring a restful night's sleep. Whether you opt for a luxury single bed or a more affordable single bed option, you can trust that our products are made with the finest materials.

  • Sunni Francis
    Sunni FrancisJun 18, 2024

    I met this guy on a dating app, we got talking and shared so many things in common,  eventually discussing future life plans and other intimate topics. At some point, the stranger promised to help me retire early through crypto trading. I was convinced to send money to coinbitjzsc.top. She showed me how to download a crypto asset wallet app and use that app to transfer funds to coinbitjzsc.top/#/. At first, I transferred small amounts to the site to make small crypto option trades. Then he said that his uncle believed there would be a bull run in the market and persuaded me to deposit more money to execute larger trades. When I tried to cash out, however, I was told by the website I had to pay a fee of around $107,000 within seven days, or additional daily fees would accrue. Although I know I had earned over $1.3 million in profit from crypto option trading, I was not able to withdraw my funds. I was so down and didn't know what to do, I read about RECOVERYCOINGROUP AT GMAILCOM and decided to contact them and have explained everything to him, he went ahead to recover 90% of my money and I am grateful he did. 

  • gunslingor
    gunslingorJun 20, 2024

    Technically your right and I agree with the point, but is disagree there is danger in using the word if it is understood by the team... which unfortunately is rarely.

    All editing is technically refactoring, so you have:

    • refactoring for features
    • refactoring for migration or obsolescence
    • refactoring for reorgization
    • refactoring for renaming
    • refactoring for redesign
    • etc.

    I.e. your example list is really the reason your refactoring, not the subject of the refactoring... the subject of refactoring usually has many overlapping reasons, which is why teams get confused both using and hearing the term... onky in the web world 🤣

  • To Thanh
    To ThanhJun 20, 2024

    Tbh when I have to report what I did yesterday and I did nothing, I would say I refactored something.

  • Inez J. Fox
    Inez J. FoxNov 16, 2024

    OstoraTVApp is a premium streaming platform offering a diverse range of live TV channels, movies, and series. Designed for seamless entertainment, it provides high-quality video content with user-friendly navigation, making it the ultimate choice for on-the-go viewing.

Add comment