From: Fabien Potencier <fabien.potencier@gmail.com>
Date: Sun, 8 Jan 2012 19:19:11 +0000 (+0100)
Subject: added coding standards in the docs
X-Git-Url: http://git.silmor.de/gitweb/?a=commitdiff_plain;h=bdcb176cc891db651326fedf35ab985cfcc08d60;p=web%2Fkonrad%2Ftwig.git

added coding standards in the docs
---

diff --git a/doc/coding_standards.rst b/doc/coding_standards.rst
new file mode 100644
index 0000000..7c0a3de
--- /dev/null
+++ b/doc/coding_standards.rst
@@ -0,0 +1,82 @@
+Coding Standards
+================
+
+When writing Twig templates, we recommend you to follow these official coding
+standards:
+
+* Put one (and only one) space after the start of a delimiter (``{{``, ``{%``,
+  and ``{#``) and before the end of a delimiter (``}}``, ``%}``, and ``#}``):
+
+  .. code-block:: jinja
+
+    {{ foo }}
+    {# comment #}
+    {% if foo %}{% endif %}
+
+  When using the whitespace control character, Do not put any spaces between it
+  and the delimiter:
+
+  .. code-block:: jinja
+
+    {{- foo -}}
+    {#- comment -#}
+    {%- if foo -%}{%- endif -%}
+
+* Put one (and only one) space before and after the following operators:
+  comparison operators (``==``, ``!=``, ``<``, ``>``, ``>=``, and ``<=``),
+  math operators (``+``, ``-``, ``/``, ``*``, ``%``, ``//``, ``**``), ``~``,
+  ``is``, ``in``, ``not``, ``and``, ``or``, and the ternary operator (``?:``):
+
+  .. code-block:: jinja
+
+     {{ 1 + 2 }}
+     {{ foo ~ bar }}
+     {{ true ? true : false }}
+
+* Put one (and only one) space after the ``:`` sign in hashes and ``,`` in
+  arrays and hashes:
+
+  .. code-block:: jinja
+
+     {{ [1, 2, 3] }}
+     {{ {'foo': 'bar'} }}
+
+* Do not put any spaces before and after string delimiters:
+
+  .. code-block:: jinja
+
+    {{ 'foo' }}
+    {{ "foo" }}
+
+* Do not put any spaces before and after the following operators: ``|``,
+  ``.``, ``..``, ``[]``:
+
+  .. code-block:: jinja
+
+    {{ foo|upper|lower }}
+    {{ user.name }}
+    {{ user[name] }}
+    {% for in in 1..12 %}{% endfor %}
+
+* Do not put any spaces before and after the parenthesis used for filter and
+  function calls:
+
+  .. code-block:: jinja
+
+     {{ foo|default('foo') }}
+     {{ range(1..10) }}
+
+* Do not put any spaces before and after the opening and the closing of arrays
+  and hashes:
+
+  .. code-block:: jinja
+
+     {{ [1, 2, 3] }}
+     {{ {'foo': 'bar'} }}
+
+* Use lower cased and underscored variable names:
+
+ .. code-block:: jinja
+
+    {% set foo = 'foo' %}
+    {% set foo_bar = 'foo' %}
diff --git a/doc/index.rst b/doc/index.rst
index 4d6c17b..55517ea 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,6 +11,7 @@ Twig
     extensions
     hacking
     recipes
+    coding_standards
     tags/index
     filters/index
     functions/index
diff --git a/doc/templates.rst b/doc/templates.rst
index 117cfea..64c72ae 100644
--- a/doc/templates.rst
+++ b/doc/templates.rst
@@ -536,8 +536,8 @@ but exists for completeness' sake. The following operators are supported:
 * ``*``: Multiplies the left operand with the right one. ``{{ 2 * 2 }}`` would
   return ``4``.
 
-* ``**``: Raises the left operand to the power of the right operand. ``{{ 2**3
-  }}`` would return ``8``.
+* ``**``: Raises the left operand to the power of the right operand. ``{{ 2 **
+  3 }}`` would return ``8``.
 
 Logic
 ~~~~~