
Ask HN: How do /you/ annotate a legacy code base? - tbirrell
We&#x27;ve all encountered those legacy code bases that are years old and thoroughly spaghettied. Ideally, you&#x27;d like to go through, reformat it all, leave comments throughout, and generally make the world a better place. However, a &quot;useless&quot; commit like that probably opens the code up to merge conflicts and other problems everyone else will get on your case about.<p>So how have you solved this problem in the past?
======
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 :)

------
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.

------
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.

