rackerlabs/developer.rackspace.com — pull request #749 by maxlinc (2014-08-04 18:19:20+00:00)
Title: Contribution guidelines: propose mustache-style syntax for placeholders

If placeholders are going to be used, I propose we use a mustache-style syntax. This doesn't change any discussions about if and when placeholders are appropriate, just the syntax we should use if they are used.

The current syntax uses single curly-braces: `{placeholder}`.
The mustache syntax uses double curly-braces: `{{placeholder}}`.

### Avoid ambiguity

The main argument for mustache is that it ambiguity. Since the use of single curly-braces for scoping or blocks is common in many languages, there are situations where the current syntax can be ambiguous. For example, this appeared in a .NET sample:

```cs
DatabaseName databaseName = new DatabaseName("{databaseName}");
UserName userName = new UserName("{username}");
UserConfiguration userConfiguration = new UserConfiguration(userName, "{password}", new DatabaseName[] {databaseName});
```

### Polyglot support

I also favor Mustache or mustache-compatible tags for placeholders because they have been [ported to every SDK language](http://mustache.github.io/). That means there's a consistent and predictable way of processing the templates.

Providing a `placeholders.json.example` or `placeholders.yaml.example` would also help consistency even easier, because it would be easy to check what placeholders and sample values each SDK is using.

**Note**: Mustache does define syntax for other tags. I think only the basic "variable" tag should be used in the snippets shown on DRC. In this context, the polyglot support is trivial. However, if we want to generate code showing the snippets in context (for projects like https://github.com/DonSchenck/GettingStarted or even an in-browser JavaScript code generator) then other tags, especially partials, may be useful.