Comments in Localization Files

[bjubes]

There has been some discussion on putting comments in localization files. Currently they are of a custom format where every line is read and whatever value is to the right of = is asigned to the key on the left.

I think it could be beneficial to add some structure to the files, which currently sit at just under 200 lines, so its easy to find keys other than just CTRL F. However the implementation has to be fast.

I'm suggesting a format where comments must be the only thing on a line (nothing like function() //comment) and are denoted by having an initial character that isn't allowed in localization, like - .

so a file may look like this:

------------------------Power------------------------
power_grid_status_online=Power Grid: <color={0}>Online</color>
power_grid_status_offline=Power Grid: <color={0}>Offline</color>
...
------------------------Furniture------------------------
furn_steel_wall=Steel Wall
furn_steel_wall_desc=A wall made out of steel.
...

Thoughts?

[koosemose]

Anything works really, but I personally would prefer we stick to common comment delimiters, so either //, #, or I suppose - since that's what Lua uses.

Any idea, offhand, if there's any significant difference in checking for a two character delimiter (such as //) over a one character delimiter?

[BraedonWooding]

YES!!!, Comments are completely needed for localisation documents, now I'm personally not too bothered what delimiter it is because it's easy to see and it's better to be consistent :D. I personally like the - one in this case because it makes nice headings but I can see why // or # could also be good.

[koosemose]

My only issue with - is that, unless it's used in series, as bjubes does in his example with a heading, it doesn't really pop out at you. Personally I'm fond of how heading type comments look with #, but that's likely because it's what I'm used to seeing in perl.

[bjubes]

Im fine with using # for that reason. I assume using a double delimiter would be slightly slower because it would require two if checks instead of just one, but timing the two is really the only way to know for sure.

[UnknownDude1]

I would say the comments should be //, because it's the most common one. And while we are there, how about / and / for multiline comments?

[databyss]

Single line comments would be easiest to deal with. Multiline comments would require additional logic and memory to process.

I put together a quick benchmark test for single/double character comment delimiter and it doesn't seem to be much of a difference.

https://gist.github.com/databyss/b31dc806abf8509a436dfd08f83076a8

[bjubes]

Because of speed, I think mutliline comments will have to just be multiple lines of single line comments.

I didn't know of String.StartsWith(), so I was assuming something like str[0] == '/' && str[1] == '/' would be slower than str[0] == '#', but thanks for the benchmark.

[databyss]

I updated the gist with tests against straight character comparison vs string.StartsWith.

That's far faster than string.StartsWith, which makes the difference even less important.

I think the speed issue is a non-factor, then, and readability/dev usage are more important.

For non-code, I tend to prefer "#", over "//" as it's just a mental reminder that I'm in a different context.