On the philosophy of task naming

Get Help
, ,
1

Sometimes I don’t think to much about it so I end up using different styles of task naming in the same project, for example:

  • Install the package (imperative form)
  • Installation of the package (noun form)
  • Installing the package (progressive form)

One ought to stick to the one form… but which one? ChatGPT is insisting that imperative form i.e “Install the package” is the best one, the recommended one and the most used one. While it makes all the sense if you are reading the code, I don’t see much sense for it when you are reading the Ansible output. Let me explain:

# Install the package               # <- Makes more sense if written in the comment
- name: "Install the package"       # <- Makes less sense because this is what the
  package:                          #    the user sees in Ansible output
  ...

The user is more interested in knowing what Ansible is currently doing and what is the current progress. This is especially true for slow tasks that loop over a number of items. So the following gives the user a nice feedback of a long running task:

- name: "Installing the package..."
  package:
  ...
  loop: "{{ package_list }}"

The noun form i.e. “Installation of the package” is like a neutral, middle ground.

The case for progressive form being the preferred one can be seen in Ansible’s internal tasks like “Gathering facts” or “Validating arguments against arg spec …”.

What are your thoughts?

  • Imperative form → Install the package
  • Noun form → Installation of the package
  • Progressive form → Installing the package
  • Other
0 voters
2

Declarative form: ‘Ensure we have <package>’

3

Should have added it as a fourth option :upside_down_face:. Don’t know if poll will keep the votes if I edit now :worried:

On the other hand, declarative “Ensure” style can also be imperative or progressive:

  1. “Ensure we have a package”
  2. “Ensuring we have a package”
4

Since the idea for Ansible to “set a state” (ie, package present/package is absent), I’d go with “Ensure we have ”

5

There are only two hard things in Computer Science: Cache invalidation and naming things :rofl:

I’m not sure if there’s an easy answer to you question. If you work alone, use whatever works best for you. If you work together with others, use whatever works best for your team.

Probably not a very helpful answer, but there it is… it depends :person_shrugging:

Personally, I think I would prefer the imperative form (“install” instead of in “installation” or “installing”). I would also prefer “install” over “ensure”, but there’s no accounting for taste.

BTW if you’re installing several packages like Apache, MySQL and PHP in a loop to create a LAMP stack, I think “install (or whatever) packages” isn’t really helpful. In that case, “install web server and dependencies” or “install LAMP stack” might be better. People will see what this task is about then. But as I’ve said: Whatever works best for you / you and your team.

1 Like
6

to add to the bikeshed, simpler imperative:

We have <package>', but as @mariolenz stated, the best naming convention is the one that makes sense to all those maintaining it.

1 Like
7

You forgot off by one errors

1 Like