How does the formatting policy look like since Ansible 2.0?

Question

I have seen multiple Ansible examples on github and in the ansible docs, e.g.:

---
# this might be in a file like handlers/handlers.yml
- name: restart apache
  service: name=apache state=restarted

Github example

The following example contains both a comment as a name.

# Make sure Jenkins starts, then configure Jenkins.
- name: Ensure Jenkins is started and runs on startup.
  service: name=jenkins state=started enabled=yes

Discussion

A name would be sufficient right or should a comment be used?

Should it be:

- name: Symlink RabbitMQ bin to sbin
  file: state=link src=/usr/lib/rabbitmq/bin dest=/usr/lib/rabbitmq/sbin

or:

#Symlink RabbitMQ bin to sbin
file: 
  state: link
  src: /usr/lib/rabbitmq/binhttp://docs.ansible.com/ansible/YAMLSyntax.html
  dest: /usr/lib/rabbitmq/sbin

When YAML Lint is consulted as recommended by the Ansible YAML syntax doc both snippets seem to be valid YAML. Although both snippets seem to be valid YAML the visual structure is different.

Questions

1. Should name (name) be used or a comment (#)?
2. Should it be file: state=link src=/usr/lib/rabbitmq/bin dest=/usr/lib/rabbitmq/sbin or should the elemented by split up, e.g. state:

Answer 1

Please understand I believe my answer to be highly subjective. Internally my team loosely agrees with my opinions on this. But we've not draft any "formatting policy" for playbooks.

1. Should name (name) be used or a comment (#)?

We only include comments if it is useful to explain the "why?" of the particular task. name is always present. The value of name will be displayed during the playbook run. In cases where a role is used as a dependency, I often parameterized name. A couple examples.

Parameterized name example, from roles/some_container/meta/main.yml

...
dependencies:
  - { role: remove_container, container_name: some_container }
...

roles/remove_container/tasks/main.yml

...
- name: Remove containers - {{ container_name }}
  docker_container:
    name: "{{ container_name }}"
    state: absent
    force_kill: true
...

Comments as complimentary to name. roles/remove_image/tasks/main.yml

# The 'docker_image' module, as of EPEL build 2.1.0.0, does not correctly handle 'tag: *' for removing all image tags.
# Below is not pretty but works on systems where you know all the image names.
- name: Remove images - {{ image_name }}
  shell: docker rmi -f $(docker images | grep {{ image_name }} | awk '{print $3}')
  register: result
  changed_when: "'requires a minimum of 1 argument' not in result.stderr"
  failed_when:
    - "'requires a minimum of 1 argument' not in result.stderr"
    - "result.rc != 0"

2. Should it be [k=v] or [k: v]?

I always use the 'k: v' syntax. Additionally I break separate values with a new line. When reading a play where someone has stuffed many 'k=v' on a single line my brain gets twisted up. I find it very difficult to juggle all the keys/values as I read along for the ones I'm interested.

Which is easier to read? I think the second example.

# 1. Launch container k=v
- name: Start A container
  docker_container:
name=containerA image=imageA published_ports='443:8443' exposed_ports=8443 volumes='/some/path:/some/path' links='b:b' env='/some/local.fact' pull=false restart_policy=always state=started

# 2. Launch container k: v
- name: Start api container
  docker_container:
    name: containerA
    image: imageB
    published_ports:
      - "443:8443"
    exposed_ports:
      - 8443
    volumes:
      - /some/path:/some/path
    links:
      - db:db
    env: /some/local.fact
    pull: false
    restart_policy: always
    state: started

I also make judicious use of white space at times.

...

# Containers a, b, c comprise 'app d' and can be updated independently.
roles:
    - { role: bootstrap_common,   tags: bootstrap  }
    - { role: bootstrap_a,        tags: bootstrap  }
    - { role: bootstrap_b,        tags: bootstrap  }
    - { role: deploy_container_a, tags: a          }
    - { role: deploy_container_b, tags: b          }
    - { role: deploy_container_c, tags: c          }
...

Answer 2

That is up to your own preference.

Comments like # Make sure Jenkins starts, then configure Jenkins. don't make much sense as they don't add more information.

Inline syntax is supported by YAML to be compatible with JSON. Outline syntax however should be preferred because, the code is better readable and code changes can be reviewed better with diff.