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.
Top comments (25)
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.
the title is stupid tbh. what the heck with these titles.
If no clicks then you're writing for nothing.
Then stop writing. Software Engineer is a science not a melodrama.
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.
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!
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.
It is, if you are the only person using the room. Thing is, you are not.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Depends on your audience. PMs don't know the difference.
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.
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.
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.