Code Structure Changes

[Anonymous Monk]

You are usually hired to change the code to achieve a change in functionality. You begin to think that if the code is written in a different way, this type of problem could easily be solved. Having short of time, you always try to change the code and commit it, but the idea that you have power to change the structure of code and you should do it, keeps bothering you. What you should do?

[LanX]

I'm struggling with a job which grew out of a 1 to a 10+ man project and is in many possible ways misdesigned.

But now I am busy to stop other colleagues "improving" things on the fly.

Changing concepts demands ...

• a clear goal,
• a well thought plan,
• good team communications
• a general agreement
• approved responsibilities
• and last but not least a willing management.

For instance I'm reluctant to let an over-motivated newbie change the data model towards a "better" one, while he doesn't understand other legacy code.

Point is it depends on the dependencies (no pun intended).

A small isolated project is easily changed, starting to "improve" complex stuff most likely ends in worsening the degree of entropy i.e. causing more chaos.

My advice:

Locate the chief architect and suggest your improvements.

He or she is the one who has to take the responsibility and decide about the strategies.

You can't be fired for following orders.

Otherwise take a sleeping pill or change the job.

[eyepopslikeamosquito]

the idea that you have power to change the structure of code and you should do it, keeps bothering you. What you should do?

Tread very carefully:

• Does the code in question have a good set of regression tests? After all, your "improvements" may introduce new bugs in working code. How will that news be received? Without the safety net of a comprehensive test suite, refactoring legacy code is suicide.
• How do you know your restructurings are "better" than the original code? Are you smarter than the original developers? Are you a better programmer? Do you understand the problem domain better? Do you have more time?

See also:

• Nobody Expects the Agile Imposition (Part VI): Architecture
• The Boy Scout Rule
• Strategies for maintenance of horrible code?

[wjw]

This breaks down into two problems as I understand it.

• You don't like the structure of the code
• You know how to improve the code(struture) to make future changes, and have the technical acumen to do so, but it is not part of the specification under which you are hired(contract)
What should one do? In my opinion...
• Complete the contract per specification and per contract(obviously)
• Approach the the lead tech and whoever has their hands on the money (perhaps one before the other, (you would have to chose which is more likely to solve your problem) and explain the advantages of the refactoring. Things like
  • an estimate of how many hours it would take(cost)
  • how many hours it would save subsequently assuming more functional changes are desired
  • other pros
  • other cons

When it boils down to it, from a contractual standpoint, making the code better outside the currently contracted specification is not your problem. Your problem is that you are diligent and wish to save the customer future expense. A laudable trait. So the best you can do in my opinion is to offer up the additional service and let the customer choose whether they want to take on that expense. And then live with their decision and 'let it go' if they choose not to take you up on it. Should they hire you in the future, you can always say no if it bothers you much.

But I am thinking that you will increase your chances of being contracted again if you make the effort, even if you are turned down. As long as you stay positive, and do not criticize the existing code base. There is a lot of difference between criticism and 'presenting opportunities" though communicating that way is pretty nuanced.

This is not so much what you "should" do as it is what you "can" do which positive for you in that you have addressed what bothers you in a positive, diligent and professional way. You end up respecting yourself for having addressed that which might benefit the customer, and respecting them either way that they decide(though that might be quantitatively and/or qualitatively less if they reject your proposal, regardless - you have shown them respect).

[holli]

It's easier to ask forgiveness than it is to get permission.

-- Grace Hopper

That path is a potential way to get fired though. To chose it, one probably has to be sufficiently "bothered" and really, really sure.

[Your Mother]

I'm late to this but it's a topic I'm fond of and missed the first pass.

…keeps bothering you. What you should do?

How much does it bother and why? Does it just offend your stylistic sensibilities? Or does it offend your conscience?

This is what I would do; and I'm vain enough that I would probably do it in both cases. I do not endorse it as a best practice.

I would put in something like double, maybe triple the time I'm being paid. I would write tests first to confirm the behavior of the parts I think should change. Then I would do the plain, minimal work, they ordered, as the billed time. Then I would do, in a different branch or tag, what I thought should be done. Ensuring both solutions pass the same tests.

Then… it's up in the air. Maybe you just flushed a bunch of time. Maybe it will never get used. Maybe your insight turned out to be naïve garbage that misunderstood the real problems involved and everything you did was unusable. Maybe it was good enough that you can negotiate a bump or bonus to add in the tests. Maybe you'll be hired again by the same folks for staying on budget and doing what you were told and then you will be able to just swap out your new stuff and with the tests, do new work in half the time and tell them so and negotiate either a bonus, since you just cut your own pay, or more time to fill out the test suite to what should also be covered.

The only thing you can lose in this is your time. You are guaranteed to gain experience and self-respect; or, as I like to call it, new shoes for your high horse.

[hippo]

I would write tests first to confirm the behavior of the parts I think should change.

Having been bitten by such things too many times I would suggest that you ensure 100% coverage of the tests before changing anything. It is far too easy to think that you've covered all the parts you intend to change without finding all the downstream traps. That said, I agree wholeheartedly with the rest of your post.

[Dallaylaen]

My current idea of handling technical debt is to keep track of how much resources it actually consumes and then make decisions.

Trying to rewrite everything in a new, shiny way leads nowhere. The warts and hacks of the old code may well be there for a reason, and you can't learn all the corner cases by just staring at the code. Which means that the new system will be just as buggy and just as hacked and full of suboptimal decisions because of time pressure. Been there, done that.

Trying to swallow your pride and get the job done leads nowhere. It hurts one as a professional and leads to passive aggression building up. In the worst case you only earn gastritis or angina.

Proposing changes and steering the discussion is a good thing. If that's not encouraged by management or ignored by colleagues, that's a bad sign about the workplace as a whole. But even if they do embrace the discussion, it's a long way to go and you get 80% of all proposals turned down. That's an uphill battle, and it has to be fought.

Writing comments that explain the legacy stuff and the reason it's done in this way is a good thing. As knowledge accumulates, it may become obvious how to clean things up without breaking them or starting from scratch.

Taking care to not break the work of others is a good thing. Even the best and shiniest API change shouldn't ruin the team's Friday night. Deprecate things gradually. If a better function cannot be trivially wrapped to emulate a worse function, it's not yet better in the first place.

Sometimes a rewrite has to be done. But it must be justified by evidence and sanctioned by the team and the business guys. Like, we wasted X money because of bugs and downtime and development of new system to this spec is Y money and Y < X.

That's my opinion. It's changing over time. I'm still learning.

[Anonymous Monk]

Grab an envelope and answer the question honestly:

who benefits and at what cost

Lessen ye be mutterin bullion and not dubloons fer thar cap'n, yarr dont fix wha'taint a'shambels

smooth sailin' iffen ye tally yer tick tocks troo