Should I comment strings?
Nearly every string format allows for comments, but does that mean you should comment each and every string?
Ask yourself, is this obvious?
The Golden Rule is to ask yourself whether the string is obvious. A button that says “OK” doesn’t need commenting, but there are many strings you may think don’t need a comment, but actually do.
The difference between working within the UI and in a string file cannot be understated. String files provide little or no visual context. Therefore, if in doubt, comment.
Double meaning words
There are many words in software which can have two meanings. In other languages this may require two words. Some common examples:
- File (the menu item) vs File (the document)
- Print (the action) vs Print (the physical print out/photo)
- Zoom (make full screen) vs Zoom (zoom in, get closer)
- Crop (the action – crop an image) vs Crop (a crop, the noun)
A common issue is when a verb (an action word) can also be a noun (a naming word). Print Something versus A Print. If it just says “Print” it’s almost impossible to decipher which exactly is meant from within the string file.
Strings using operators
It is necessary to comment all strings which include operators (e.g. %@, %i, %d, etc). This is because, without seeing the completed string, the string itself provides little context. For example:
- “Hello, %@” (Name? Company Name? What should go here?)
- “%i out of %i” (Big numbers, small numbers?)
- “%@ > %d” (What is greater than that number)
- “Welcome %@, to the %@. In %i s you will be joined by %@” (Give an example sentence)
Whenever you code these strings, ask yourself “If this is all I see, would I understand this string?” That’s usually a good indicator. Remember, what may seem obvious to you as a developer, isn’t always to someone remote and outside of the project.
When not to comment
It’s not always necessary to comment however. Some strings are inherently understandable and therefore commenting is going to waste time (and increase file size!). Examples of obvious strings (there are an infinite amount here):
- “No Message Selected”
- “Print Page…”
- “Sketch your thoughts.”
- “Start enjoying these features today.”
- And many many more…