HN Explorer

Ask HN: How do /you/ annotate a legacy code base?

5 points by amflare ↗ HN
We've all encountered those legacy code bases that are years old and thoroughly spaghettied. Ideally, you'd like to go through, reformat it all, leave comments throughout, and generally make the world a better place. However, a "useless" commit like that probably opens the code up to merge conflicts and other problems everyone else will get on your case about.

So how have you solved this problem in the past?

5 comments

[ 3.4 ms ] story [ 18.1 ms ] thread
marsrover
How do you eat an elephant? One bite at a time.

Sure, a mass refactoring is going to cause a lot of pain to merge in, but you shouldn't be making massive pull requests in the first place. I don't think small refactoring here and there should be an issue. It's not like we've never dealt with merge conflicts before.

If your company is discouraging refactoring because it will cause merge conflicts, that's probably not a good sign of things to come.

marktangotango
OP didn't mention refactoring, but did mention reformatting? Maybe OP can clarify.

In past I've done one big tabs to spaces, trim line ending whitespqce, cr ln to ln, indent cleanup commit. Hardly anyone can object to that!

So far as comments I've create multi page wiki documents of the high to medium level architecture. A trail of breadcrumbs in the maze for the next guy/gal.

Problem is, those efforts take a lot out of me personally, that stuff sticks in my head years later. Not fun to have the crap i worked on 10 years still on there, I NEED that space :)

Jtsummers
It's an office politics issue. Here we have little issue with it, but I worked in a place that didn't like handling lots of "clean up" commits. The main issue is (working in embedded avionics systems) code changes have to be peer reviewed and qualified. So I've tried to make sure my changes are part of some new or existing PR. I can't do it willy-nilly or I'll be asked, "Why did foo.c:145-150 change?" If it's not part of a PR I can't justify it. So when I stumble on problems, I put them in JIRA. Even if the "problem" is: 200 lines of code without a single comment, all variables have names like XYZ12, XYZ13. It may technically work, but no one knows why and, fortunately, falls afoul of our coding guidelines. I may not be able to work it today, but it's in the system and can be worked at some point when priorities align better.
bbcbasic
Refactor code while no one else is working on that module, and ask everyone to pull/update once you are done so they start their changes post-refactoring.
kenshi
> However, a "useless" commit like that probably opens the code up to merge conflicts and other problems everyone else will get on your case about.

That is a social problem not a technical one.

You need to sell the idea to your team to try to improve the code base with every commit you do. Every time you need to make changes in some source file, see what clean up you can do to it as well.

Depending on the morale/motivation/priorities of the team, this can be a harder sell than it should be.

Lead by example. Show good judgement on how much to do. Small changes accumulate fast. Don't upset/hinder people by changing vast tracts of code that they need to work on.

As a great VP of Engineering I once had the fortune to work with told me: Software engineering is a team sport.