Hi, I have a little request for developers who create strings:
Whenever you introduce a new string, please add a comment which describes the context of the string unless the context is either obvious or unimportant. With “context” I mean the place where the string is used.
Here is a guide to what kind of comment I am looking for, depending on the string content:
[ul][]Onomatopoeia (“Crash!”, “Boom!”, “Bang!”): The event which makes such a sound.
[]Neologisms you invented yourself (“power armor”, “hauling frame” “razorbar katar”): Explain all of them unless the string in question explains it.
[]Neologisms someone else invented (“dark wyrm”, “jabberwock”, “boomer”): Explain all of them unless the string in question explain it. If you think it’s important, also mention the source of the word.
[]Terms you are unlikely to find in a dictionary: Explain them
[]Inside jokes: Explanation and context
[]String fragments, half-sentences, etc.: Context (where they are used)
[]Abbreviations: Write them out (better safe than sorry)
[]Complex format strings: Context and the meaning of all the parameters
[]Menu items: What happens if the menu item is used.
[]Strings with a “hard” length limit: The length limit.
[*]Everything else: Does probably not need to be commented.[/ul]
Above items also apply if the category in question is only a part of the string. Example: If you have an abbreviation inside a long string which is otherwise pretty self-explanationary, the comment for such a string should still include the meaning of the abbreviation.
Here’s an example on how to use this list: If you have a string “Boom!” and it appears when a grenade explodes, you have a string which belongs to the “onomatopoeia” category. A good comment should therefore read like “That’s the sound made by an exploding grenade.”.
The WTF Thread has a lot of more examples for strings which badly need comments as well. I posted some examples of neologisms in Errors in English strings.
The reason why I am requesting this is simple: It would ease the life of translators a lot. 