diff options
Diffstat (limited to 'docs/style_guide.adoc')
| -rw-r--r-- | docs/style_guide.adoc | 51 |
1 files changed, 41 insertions, 10 deletions
diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc index 714b56c70..3b888db12 100644 --- a/docs/style_guide.adoc +++ b/docs/style_guide.adoc @@ -4,16 +4,47 @@ The purpose of this guide is to describe the preferred coding conventions used in this repository (both in ansible and python). -It is important to note that this repository may not currently comply with all style guide rules, but our intention is that it will. +It is important to note that this repository may not currently comply with all style guide rules, but the intention is that it will. All new pull requests created against this repository MUST comply with this guide. This style guide complies with https://www.ietf.org/rfc/rfc2119.txt[RFC2119]. -== Ansible Variable Naming +== Python -=== Global Variables -We define Ansible global variables as any variables outside of ansible roles. Examples include playbook variables, variables passed in on the cli, etc. + +=== Python Maximum Line Length + +.Context: +* https://www.python.org/dev/peps/pep-0008/#maximum-line-length[Python Pep8 Line Length] + +''' +[cols="2v,v"] +|=== +| **Rule** +| All lines SHOULD be no longer than 80 characters. +|=== + +Every attempt SHOULD be made to comply with this soft line length limit, and only when it makes the code more readable should this be violated. + +Code readability is subjective, therefore pull-requests SHOULD still be merged, even if they violate this soft limit as it is up to the individual contributor to determine if they should violate the 80 character soft limit. + + +''' +[cols="2v,v"] +|=== +| **Rule** +| All lines MUST be no longer than 120 characters. +|=== + +This is a hard limit and is enforced by the build bot. This check MUST NOT be disabled. + + + +== Ansible + +=== Ansible Global Variables +Ansible global variables are defined as any variables outside of ansible roles. Examples include playbook variables, variables passed in on the cli, etc. ''' [cols="2v,v"] @@ -29,8 +60,8 @@ Example: g_environment: someval ---- -==== Role Variables -We define Ansible role variables as variables contained in (or passed into) a role. +=== Ansible Role Variables +Ansible role variables are defined as variables contained in (or passed into) a role. ''' [cols="2v,v"] @@ -39,7 +70,7 @@ We define Ansible role variables as variables contained in (or passed into) a ro | Role variables MUST have a prefix of atleast 3 characters. See below for specific naming rules. |=== -===== Role with 3 (or more) words in the name +==== Role with 3 (or more) words in the name Take the first letter of each of the words. @@ -61,7 +92,7 @@ tmur_var1: value_one -===== Role with 2 (or less) words in the name +==== Role with 2 (or less) words in the name Make up a prefix that makes sense. @@ -82,7 +113,7 @@ tow_var1: value_one ---- -===== Role name prefix conflicts +==== Role name prefix conflicts If two role names contain words that start with the same letters, it will seem like their prefixes would conflict. Role variables are confined to the roles themselves, so this is actually only a problem if one of the roles depends on the other role (or uses includes into the other role). @@ -104,4 +135,4 @@ Even though both roles have the same prefix (mur), and even though both roles ha This would only be a problem if my_uber_role depended on made_up_role, or vice versa. Or if either of these two roles included things from the other. -We think this is enough of a corner case that it is unlikely to happen. If it does, we will address it on a case by case basis. +This is enough of a corner case that it is unlikely to happen. If it does, it will be addressed on a case by case basis. |