Update template best practices regarding chomping

Signed-off-by: Erik Sundell <[email protected]>

Author: consideRatio

content/en/docs/chart_best_practices/templates.md

@@ -31,58 +31,81 @@ For that reason, _all defined template names should be namespaced._
 Correct:
 
 ```yaml
-{{- define "nginx.fullname" }}
-{{/* ... */}}
-{{ end -}}
+{{- define "nginx.fullname" -}}
+# ...
+{{- end }}
 ```
 
 Incorrect:
 
 ```yaml
 {{- define "fullname" -}}
-{{/* ... */}}
-{{ end -}}
+# ...
+{{- end }}
 ```
+
 It is highly recommended that new charts are created via `helm create` command
 as the template names are automatically defined as per this best practice.
 
 ## Formatting Templates
 
 Templates should be indented using _two spaces_ (never tabs).
 
-Template directives should have whitespace after the opening  braces and before
+Template directives should have whitespace after the opening braces and before
 the closing braces:
 
 Correct:
-```
-{{ .foo }}
-{{ print "foo" }}
-{{- print "bar" -}}
+
+```yaml
+{{- /* Conditionally create service account */}}
+{{- if .Values.serviceAccount.create }}
+apiVersion: v1
+# ...
+{{- end }}
 ```
 
 Incorrect:
+
+```yaml
+{{-/* This comment is even a syntax error */}}
+{{-if .Values.serviceAccount.create}}
+apiVersion: v1
+# ...
+{{-end}}
 ```
-{{.foo}}
-{{print "foo"}}
-{{-print "bar"-}}
+
+Templates should chomp unnecessary whitespace. A good practice is to
+systematically _chomp left_, but also _chomp right_ for initial content in a
+template file or defined template.
+
+```yaml
+myList:
+  {{- range .Values.elements }}
+  - {{ . }
+  {{- end }}
 ```
 
-Templates should chomp whitespace where possible:
+```yaml
+{{- define "nginx.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "nginx.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+```
 
 ```yaml
-foo:
-  {{- range .Values.items }}
-  {{ . }}
-  {{ end -}}
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+# ...
+{{- end }}
 ```
 
 Blocks (such as control structures) may be indented to indicate flow of the
 template code.
 
-```
-{{ if $foo -}}
-  {{- with .Bar }}Hello{{ end -}}
-{{- end -}}
+```yaml
+{{- range .Values.elements }}
+  {{- print "my element is" . }}
+{{- end }}
 ```
 
 However, since YAML is a whitespace-oriented language, it is often not possible
@@ -147,17 +170,23 @@ metadata:
 Both YAML and Helm Templates have comment markers.
 
 YAML comments:
+
 ```yaml
 # This is a comment
 type: sprocket
+foo: bar # This is a comment, bar isn't
 ```
 
-Template Comments:
+Helm template comments:
+
 ```yaml
-{{- /*
-This is a comment.
-*/ -}}
+{{- /* This is a comment (with chomping to the right). */ -}}
 type: frobnitz
+
+{{- /*
+This is a multiline comment (with no chomping to the right).
+*/}}
+foo: bar
 ```
 
 Template comments should be used when documenting features of a template, such
@@ -166,11 +195,10 @@ as explaining a defined template:
 ```yaml
 {{- /*
 mychart.shortname provides a 6 char truncated version of the release name.
-*/ -}}
-{{ define "mychart.shortname" -}}
-{{ .Release.Name | trunc 6 }}
-{{- end -}}
-
+*/}}
+{{- define "mychart.shortname" -}}
+{{ .Release.Name | trunc 6 | trimSuffix "-" }}
+{{- end }}
 ```
 
 Inside of templates, YAML comments may be used when it is useful for Helm users