Handling source code table alignment

Question

Sometimes there is need to have tables (big or small) in source code.

ItemType const SomeTable[] = {
    //   id  name  min  max
    ITEM( 3, "Foo", 70, 180),
    ITEM(13, "Bar", 30,  50),
    ITEM(14, "Baz", 30,  60),
    ITEM(60, "Abc",  1,   4),
};

Over time new lines are added and existing ones changed:

ItemType const SomeTable[] = {
    //   id  name  min  max
    ITEM( 3, "Foo", 70, 180),
    ITEM(13, "BetterBar", 30,  50),
    ITEM(14, "Baz", BAZ_MIN, BAZ_MAX),
    ITEM(60, "Abc",  1,   4),
    ITEM(80, "AAAAAA", 0, A_COUNT),
    ITEM(81, "BBB  BBBB B", 0, B_COUNT),
};

That looks horrible. We can fix the alignment:

ItemType const SomeTable[] = {
    //   id  name               min      max
    ITEM( 3, "Foo"        ,      70,     180),
    ITEM(13, "BetterBar"  ,      30,      50),
    ITEM(14, "Baz"        , BAZ_MIN, BAZ_MAX),
    ITEM(60, "Abc"        ,       1,       4),
    ITEM(80, "AAAAAA"     ,       0, A_COUNT),
    ITEM(81, "BBB  BBBB B",       0, B_COUNT),
};

Looks better, but the actual change is lost. If you look at the version control diff, it's nearly impossible to see what was added as whole table has been rewritten. This is especially bad if tables are several hundred lines big, as they tend to be.

Estimating table sizes in advance is possible, but in practice they tend to be off: either too small, in which case they were useless, or too big in which case lot of readability is lost.

Surely someone has figured out a good strategy for handling these cases. It doesn't have to be perfect system, as long as it is reasonably readable.

---

Following things are out of the scope of the question:

• Using external data files: Target platform may not have file system.

• Using external script/conversion tool to convert data file into code: Introduces extra dependency, which may not be possible or preferred.

---

I'd like to keep this question language agnostic, but typical situation where I have this problem is in embedded C projects. For example, special purpose library for several different platforms. So I basically have only have the preprocesser at my disposal, and X-macros only go so far.

Answer 1

One possible kludge which would allow you to keep you change history but align your code correctly would be to comment out the entire existing table. And add a new correctly aligned table after it.

This would/should be recorded as just two changes in the source code.

After the new table been saved in the repository you can delete the commented out section on the next change (again logged as a single change!).

This may or may not work depending on how clever your version control software is.

On a more general note I (nearly always when I am being good and someone may be watching) code tables like this as a separate class/function. This helps keep the main body of the code readable and allows for easy switching to an external file/xml/database/web service at a later date.

Answer 2

If you look at the version control diff, it's nearly impossible to see what was added as whole table has been rewritten

Then don't look at the version control diff.

For instance WinMerge, which is free & runs on both Windows & Linux has an option " Line differences with Whitespace: Ignoring all".

Couldn't you use that? It won't show those alignment adjustments as changed lines.

And if your version control diff doesn't offer something similar, then why not email and ask them to add it? Or code it yourself, if your version control is FOSS.

Answer 3

What if you auto-generate the file which contains the table declaration?

Since it is auto-generated, you never need to diff that legible file itself. Diffing the input file will show only truly changed lines, since you will never reformat the input file to make it more legible.

Q.E.D :-)