I find that I sometimes use placeholders in strings, like this:
$ cat example-apache
<VirtualHost *:80>
ServerName ##DOMAIN_NAME##
ServerAlias www.##DOMAIN_NAME##
DocumentRoot /var/www/##DOMAIN_NAME##/public_html
</VirtualHost>
Now I am sure that it is a minor issue if the placeholder is ##DOMAIN_NAME##, !!DOMAIN_NAME!!, {{DOMAIN_NAME}}, or some other variant. However, I now need to standardize with other developers on a project, and we all have a vested interest in having our own placeholder format made standard in the organization. Are there any good reasons for choosing any of these, or others? I am trying to quantify these considerations:
- Aesthetics and usability. For example,
__dict__may be hard to read as we don’t know how many underscores are in there. - Compatibility. Will some language try to do something funny with
{}syntax in a string (such as PHP does with"Welcome to {$siteName} today!")? Actually, I know that PHP and Python won’t, but others? Will a C++ preprocessor choke on##format? If I need to store the value in some SQL engine, will it not consider something a comment? Any other pitfalls to be wary of? - Maintainability. Will the new guy mistake
##SOME_PLACEHOLDER##as a language construct? - The unknown. Surely the wise folk here will think of other aspects of this decision that I have not thought of.
I might be bikeshedding this, but if there are real issues that might be lurking then I would certainly like to know about them before mandating that our developers adhere to a potentially-problematic convention.
2
I use placeholders myself, and over the years have sedimented the following considerations, in descending priority:
- no escape sequences or quote symbols, they are awkward everywhere:
' " - no shell metacharacters, for I often use scripts. Avoid:
$ < > ( ) { } | !and backticks - no regexp-risky characters, searching which could be an escape nightmare:
. - * ? - no common and mathematical operators:
, + - / * - no UTF-8 or higher ASCII characters that can mess binary searches
This leaves few candidates: % : ^ # _ @ ; (where ^ and % are often operators and ought to be excluded).
Personally, I use the last three – # _ @
Language constructs would probably lead to eschew %, :, ; @ and ^ (even if @@@DOMAIN_NAME@@@ is a nice kick in the teeth: you can’t miss it).
Using fixed length fonts, I use indifferently _ and #. Maybe I’m more inclined on __THIS_FORM__ which is even legal in C (danger, Will Robinson! You might have C constants formatted like that!).
I think that # is a better choice if you have legibility issues. ###DOMAIN_NAME### looks pretty good and is unlikely to come by in any language I’m familiar with. And ###_DOMAIN_NAME_### is more complicated, but maybe more readable.
Of course in some specific domains you might actually want to ape some existing schemes (e.g. use shell metacharacters), either to make it clearer that those strings are really placeholders, or because you can leverage (with all due care) some tool to expand them: hence e.g. {{ varname }}, ${ varname }, $(varname) or [[ varname ]].
In scripts such as VirtualHosts, I tend to use @@@NAMES@@@… maybe I shouldn’t have attempted to answer, since I’m unable to agree on one standard even with myself!
3
Take a look at some projects that you admire and follow their convention.
Don’t make up something new, try to find out what a typical convention is and go with it.
Make sure to include a way to escape that character sequence so you can include it as a literal without it being interpreted as a token.
3
In the weeks since I first asked this question, I’ve learned which characters to avoid. I list them here for my own use and for others:
- Avoid
*and_as some issue-tracking software (such as redmine) use these for wiki-syntax and they will replace the values in copy-pasted bug reports. - Bash absolutely chokes on
!, in fact you cannot even up-arrow to get the back back to fix the line.