> There are step-by-step instructions in the comments explaining what's going on.
This is a big red flag. As everyone has been saying since decades, comments are for the why, not the what.
Also, recall should be upper bound to the time it takes to find the relevant commit message. Having to actually recall from my brain why something was done is a terrible way to work: presumably at most two people in the original group know why, the people may not even be there anymore, and recall is far from perfect.
Without seeing the code, none of us can say whether this is problematic or not. The post explicitly says the code has intrinsic complexity, so it seems very plausible that the comments do explain what's going on. Perhaps they are like:
// Step 1: Prepare the widget
... 10 lines of code ...
// Step 2: Fnagle the widget
... 10 lines of code ...
Some (Martin Fowler in Refactoring) would respond to this by putting each of those 10-line code blocks into their own functions call step_1_prepare_widget() etc., but many times (not always) this ends up making the code harder to follow.
That last part's gonna need a citation. I've never experienced a difference myself. Once methods get big, assuming no usage of IDE functions (regions), going through these large code sequences will quickly fill my mental space, whereas stashing away the code in methods does not.
On the flip side, smaller methods do not encourage code duplication and help set up unit testing for those who desire it. There are also arguments to be made depending on language and coding style (e.g. encouraging guarding, early returns and avoiding bracket use and indentation in old imperative-style Java).
The only citation can be experience, especially since it's so heavily dependent on the specifics of the situation.
If the refactored mini-function captures something very discrete, like popping an item off of a queue, then of course it's a big win. You'll often ask yourself what the hell the original developer was thinking spilling all these details into an unrelated context.
But if that chunk of code only really makes sense in the context of that function, then moving it into a separate function might not do anything except force future readers to flick back and forth between between the various helper functions and the top-level coordinating function. Have you honestly never had that experience? If so, maybe you're lucky enough to have never worked on a code base containing that mistake.
The only true rule is never to blindly follow rules! Feel free to bear good practices in mind, but always make a new, independent assessment for each situation where you might apply it. For the rule about refactoring into smaller functions, think about whether future readers are indeed going to be able to (confidently) avoid looking at the implementation of those smaller functions, because their meaning is so clear from their signature, or if you're just adding extra navigation and mental work. Sometimes it will go one way, maybe even mostly it will go that way, but sometimes not.
The last paragraph ended up more preachy and patronising than I meant. All I meant was, I've certainly come across code from devs that followed rules too blindly.
One of the more memorable comments I’ve seen is “this is a terrible hack that should be fixed as soon as someone is willing to pay for it.” It’s been live for over 10 years. Reminder that in the greater scheme of things, it’s all about money.
Got a real kick out of this blog post as it seems to imply that code written two years ago is "old".
I've been surprised quite a few times in the past year that what I thought was "relatively new" code actually ended up being 5+ years old when I went back and looked at the commit history.
Heh yeah I have the same, I keep thinking of this module I made as just being released into production a few months ago but yeah it's been three years now. Time flies!
They're referring to the "debt" bit of "technical debt". If you default on a loan then that means you did not pay back a payment that is due, at least not on time. If this happens enough in real life you might end up with bankruptcy. If you could default on a loan and suffer no consequences then it might happen more often!
i've been thinking about this a lot after my post-burnout brain has slowed considerably as i've gotten older (30). i definitely know i'm not as quick as i used to be.
i've noticed that even after 3 weeks, code that i wrote deep in the flow zone will feel completely foreign, so it's more like a linear curve up and then it plateaus. however, i feel like at my current trend, by the time i'm 50 code i write the day before will feel completely foreign.
i used to watch this trend when i worked with programmers older than me, but i never realized just how badly it would hit me.
If I recall correctly you loose 10% of your axones every ten years, same for testosterone btw
Yes everybody should eat testosterone pills to offset the natural loss but people do not have sufficient mental health to do it
I think Adam Tornhill has a nice take on this. He recommends tech debt not be quantified as such, but encourages focusing on areas with high complexity and large churn
Definitely got something here - legacy code becomes that way by mostly working, not by being constantly changed or rewritten. Though constant changes may also be applied to legacy code.
>>
One common developer bias is that old code is bad. You've never heard anyone say the phrase "legacy code" without contempt in their tone
>>
As for the 'code age' point, I'd think it is more related to recency of the requirements, when was that problem domain last worked on and understood.
So maybe the issue points to clarity of requirements capture, and perhaps the coding/design corresponding to the requirements.
Another commenter referred to automated testing, which hits on having test cases to match the requirements. With that level of functional documentation, the code is likely to be easier to understand.
I've seen this happen not because the code is hard to read but brittle. We tried and tried to clean it up but it was hard to tell if we were making a dent on code quality. Then a third party added a test system and we started writing automated tests. The code was a dream to work with.
I cannot overstate how much better it was to work with.
There were internal attitudes that prevented me from pushing for tests. Oh and the fact that the company had not used them in the past. But I regret not pushing hard for testing.
This is a big red flag. As everyone has been saying since decades, comments are for the why, not the what.
Also, recall should be upper bound to the time it takes to find the relevant commit message. Having to actually recall from my brain why something was done is a terrible way to work: presumably at most two people in the original group know why, the people may not even be there anymore, and recall is far from perfect.