Dotnotatie versus bracketnotatie in Ansible en Jinja

Probleem

Zowel dotnotatie als bracketnotatie zijn geldig in Ansible- en Jinja-expressies. Zonder een duidelijke regel ontstaan in codebases mengsels van stijlen zoals item.name, item['groups'] en item[var_name].

Deze inconsistentie maakt code moeilijker scanbaar en te reviewen. Het zorgt ook voor ruis in voorbeelden en documentatie, omdat lezers moeten afleiden of de wijziging in syntax betekenisvol is of slechts stilistisch.

Context

De Ansible-documentatie gebruikt veelal dotnotatie in voorbeelden, zoals item.name, item.groups, item.key en item.value.role.

Jinja ondersteunt zowel foo.bar als foo['bar']. Bracketnotatie is echter flexibeler omdat het ook dynamische sleutels ondersteunt zoals foo[var_name].

In de huidige C2 Platform Ansible-code wordt bracketnotatie op veel plaatsen gebruikt en is het feitelijk de bestaande huisstijl. Deze richtlijn definieert de gewenste toekomstige richting: gebruik standaard dotnotatie voor vaste sleutels, terwijl bestaande code grotendeels nog gestandaardiseerd is op bracketnotatie.

Oplossing

1. Gebruik bij voorkeur dotnotatie voor vaste sleutels.
2. Gebruik bracketnotatie alleen wanneer dotnotatie de lookup niet veilig of correct kan uitdrukken.
3. Gebruik bracketnotatie voor dynamische sleutels, bijvoorbeeld item[var_name].
4. Vermijd het mengen van dot- en bracketnotatie in dezelfde taak of hetzelfde bestand zonder duidelijke reden.
5. Bij het bewerken van bestaande C2 Platform-code geef je lokale consistentie prioriteit, tenzij je bewust een breder blok refactor naar de nieuwe voorkeursstijl.

Voordelen

• Nieuwe code sluit beter aan bij veelgebruikte Ansible-voorbeelden.
• Expressies zijn makkelijker te typen omdat dotnotatie minder en eenvoudigere toetsaanslagen vereist dan bracketnotatie.
• Past bij de C2 Platform luie naamgevingsconventie , die eenvoudiger typen prefereert boven onnodige complexiteit.
• Houdt bracketnotatie beschikbaar voor gevallen waarin het echt nodig is.

Alternatieven (optioneel)

Het overal gebruiken van bracketnotatie is geldig en komt overeen met een groot deel van de huidige C2 Platform-codebase, maar het is uitgebreider en moet niet de voorkeursstijl blijven voor nieuwe code.

Voorbeelden en implementatie

Gebruik bij voorkeur dotnotatie voor vaste sleutels

- name: Configure Apache vhost
  ansible.builtin.debug:
    msg: "{{ item.servername }} -> {{ item.documentroot }}"
  loop: "{{ apache_vhosts }}"

Voor vaste sleutels is dotnotatie korter en makkelijker scanbaar.

Gebruik bracketnotatie voor dynamische sleutels

- name: Show selected vhost field
  ansible.builtin.debug:
    msg: "{{ item[field_name] }}"
  loop: "{{ apache_vhosts }}"

Hier is bracketnotatie vereist omdat de sleutel is opgeslagen in field_name.

Vermijd het mengen van stijlen zonder reden

- name: Avoid mixed notation
  ansible.builtin.debug:
    msg: "{{ item.servername }} -> {{ item['documentroot'] }}"
  loop: "{{ apache_vhosts }}"

Deze stijl is geldig maar niet aanbevolen. Gebruik één stijl consistent, tenzij de expressie bracketnotatie vereist.

Aanvullende informatie

• Houd variabele- en identifiernamen kort en consistent: Geef de voorkeur aan korte, consistente namen die ruis verminderen zonder variabelen of identifiers onduidelijk te maken.
• Loops — Ansible Community Documentation 
• Using variables — Ansible Community Documentation 
• Variables — Jinja Template Designer Documentation