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 (27)
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.
When you fix human nature, Seisgasse, you let us know! Until then article titles will be click-baity. Waiting on you!
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, 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 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.
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.
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:
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 🤣
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.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.