7

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:

  1. Aesthetics and usability. For example, __dict__ may be hard to read as we don't know how many underscores are in there.
  2. 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?
  3. Maintainability. Will the new guy mistake ##SOME_PLACEHOLDER## as a language construct?
  4. 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
    Are these files used only to document the expected data format? There are many macro processors that interpolate values into strings. Why not pick one of them? – kevin cline Jun 27 '13 at 16:59
  • 1
    Just went through this decision while making a templating engine. I ended up going with {{text}}, since the other templating systems I use seem to be converging on that. And its very readable. – GrandmasterB Jun 27 '13 at 18:18
9

I use placeholders myself, and over the years have sedimented the following considerations, in descending priority:

  • absolutely no shell metacharacters, for I often use scripts. Avoid: $ < > ( ) { } |
  • no escape sequences: \
  • no regexp-risky characters, searching which could be an escape nightmare: . - * ? ' "
  • no common and mathematical operators: + - / *

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!

  • And yet, your answer embodies exactly most of my concerns and you've addressed them! – dotancohen Jun 27 '13 at 16:13
  • 1
    + regexp-risky == wildcards+ ... speaking of which, I would add common math symbols, like +, -, /, %, *, and ^ as ones I would like to avoid/avoid seeing. – JustinC Jun 27 '13 at 19:36
  • Absolutely. I hadn't even taken them into account, but that's a good point, thanks! – LSerni Jun 27 '13 at 21:40
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.

  • That is a good idea about the escaping. Generally, though, it would be implemented by replacing the entire ##SOME_VALUE## and not by parsing for ##. I will try to troll some large software projects such as Mozilla or the Linux kernel for examples, but I fear that those may have examples that work in one language but have pitfalls in another. – dotancohen Jun 27 '13 at 16:01
  • Templating is very common in web frameworks, for example Django. – M. Dudley Jun 27 '13 at 16:07
  • +1 for the escaping. I have never needed it... so far... but I'll be sure to keep it in mind should I ever do! – LSerni Jun 27 '13 at 16:10
2

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.