The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
You are encouraged to add the dotfiles from this repository to your project, and use an editor/IDE which understands them โ otherwise, know how to apply these rules to your files manually.
-
YAML documents (including Ansible playbooks) MUST begin a document with
---
followed by one empty line.--- # Begin playbook...
-
Every task MUST have a
name
. -
Every task MUST have 1 or more appropriate tags, annotated as an array instead of a single string.
# Good tags: - abc # Bad tags: abc
-
You SHOULD use the built-in Ansible task (when available) instead of simply calling-out to the shell. See Ansible: List of all modules for more information. In certain cases, Ansible actions are not yet powerful enough to replace Bash actions.
-
Any use of
when
SHOULD happen after the primary action (e.g., "do this thing when this condition is met"). -
Binary decisions MUST use
yes
/no
instead oftrue
/false
.
-
Indentation should be 2 spaces. Further, arrays (i.e., lines which begin with
-
) should be indented 2 spaces from its parent as well. -
Line-endings MUST use the
\n
character (LF
) used by default on Mac OS X and *nix systems. -
Lines MUST NOT have trailing whitespace.
-
A file MUST end with a single empty line feed.
-
Files MUST use only UTF-8 without BOM as its character encoding.
-
Files SHOULD have soft-limit of
80
characters per line. Valid exceptions are when you have an unbreaking line. -
Files SHOULD use long-form YAML, not short-form YAML.
# Good - name: Make new symlink file: state: link owner: root group: root src: /usr/local/okapi/{{ version }} path: /usr/local/okapi/okapi_new # Bad - name: Make new symlink file: state=link owner=root group=root src=/usr/local/okapi/{{ version }} path=/usr/local/okapi/okapi_new
-
Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.
-
For readability, comments MUST have a single space after
#
.# Good Comment #Bad Comment # Bad Comment # Bad Comment
-
There SHOULD always be one line of whitespace above the start of a comment block.
# This is my code. key: ansible_command # This is more code. key: another_ansible_command
-
For inline comments (e.g., commenting-out a line), the comment MUST begin after the appropriate indentation, prefixing the line with a
#
(hash-space). You MUST NOT add a#
to the beginning of a line, being irrespective of indentation.# Good abc: def: # - 123 - 456 - 789 # Bad abc: def: # - 123 - 456 - 789
If there is ever a discrepancy between English-speaking dialects, use U.S. English as a baseline for both spelling and word choice. Grammarist and similar websites can help ensure intended usage.
color (correct)
colour (incorrect)
spelled (correct)
spelt (incorrect)
canceled (correct)
cancelled (incorrect)
labeled (correct)
labelled (incorrect)
math (correct)
maths (incorrect)
apartment (correct)
flat (incorrect)
"Apple is very successful." (correct)
"Apple are very successful." (incorrect)