# RFC: Module conventions / check list **URL:** \ **Category:** Ansible Developer\ **Created:** [May 16, 2015, 9:30am UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245 "2015-05-16T09:30:54Z")\ **Posts on this page:** 9\ **Page:** 1
**Author:** ![Rene\_Moser](https://avatars.discourse-cdn.com/v4/letter/r/7bcc69/32.png) [@Rene\_Moser](https://forum.ansible.com/u/Rene_Moser)\ **Post date:** [May 16, 2015, 9:30am UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/1 "2015-05-16T09:30:54Z")
Hi I would like to share some infos about what I look for in modules, or what I learned, what does make a module a good module. It resulted in some kind of checklist for reviewers or module developers, maybe it helps for others or could be extended and formated for docs.ansible.com: \* Documentation    \* available?    \* Remove unnecessary doc like `aliases: `?    \* `default: null for `required: true` is not necessary, removed?    \* version not a float number and value the current development version?    \* arguments camelCase snake\_case mixed? --\> Prefer snake\_case.    \* arguments in doc and dict identical?    \* password / secret arguments no\_log=True set?    \* Requirements documented?    \* Author set? New format for extras repo?    \* Made use of U() for urls, C() for files and options, I() for params, M() for modules? \* GPL License header? \* Examples    \* available?    \* reproducible? \* Module use check\_mode? Could it be modified to use it? Documented? \* Module handles exception? (exceptions are bugs) \* Ensure module not uses sys.exit() --\> fail\_json() from util \* import custom packages in try/except and handled with fail\_json() in main() e.g.    try:      import foo      HAS\_LIB=True    except:      HAS\_LIB=False \* Are module actions idempotent? If not --\> Documented in notes? \* import module snippets `from ansible.module_utils.basic import *`? at the bottom? ---
**Author:** ![Brian\_Coca](https://avatars.discourse-cdn.com/v4/letter/b/6de8d8/32.png) [@Brian\_Coca](https://forum.ansible.com/u/Brian_Coca)\ **Post date:** [May 16, 2015, 3:58pm UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/2 "2015-05-16T15:58:06Z")
Very nice, this is very helpful, I'll ping the team and probably add this to the development docs. also, I would add: - shebang should always be #!/usr/bin/python - required should always be present, be it true or false - if required is false you need to document default, even if its 'null' - as stated, uncaught exceptions are bugs, give out useful messages on what you were doing and you can add the exception message to that. - avoid catchall exceptions, they are not very useful unless the underlying API gives very good error messages pertaining the attempted action. - try to normalize parameters with other modules, you can have aliases for when user is more familiar with underlying API name for the option - pep8 is nice, but not a requirement. Specifically, the 80 column limit now hinders readability more that it improves it (even when reading code on my phone) - avoid 'action/command', they are imperative and not declarative, there are other ways to express the same thing - sometimes you want to split the module, specially if you are adding a list/info state, you want a \_facts version - if you are asking 'how can i have a module execute other modules' ... you want to write a role ---
**Author:** ![Greg\_DeKoenigsberg1](https://avatars.discourse-cdn.com/v4/letter/g/838e76/32.png) [@Greg\_DeKoenigsberg1](https://forum.ansible.com/u/Greg_DeKoenigsberg1)\ **Post date:** [May 16, 2015, 6:06pm UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/3 "2015-05-16T18:06:52Z")
Thanks Rene. Badly needed and a good start. My hope is that this can turn into a checklist that will allow anyone to do triage on new module submissions. ---
**Author:** ![Serge\_van\_Ginderacht](https://avatars.discourse-cdn.com/v4/letter/s/b782af/32.png) [@Serge\_van\_Ginderacht](https://forum.ansible.com/u/Serge_van_Ginderacht)\ **Post date:** [May 16, 2015, 6:51pm UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/4 "2015-05-16T18:51:39Z")
Perhaps a couple of these can be implemented as tests? ---
**Author:** ![Jesse\_Keating](https://avatars.discourse-cdn.com/v4/letter/j/3bc359/32.png) [@Jesse\_Keating](https://forum.ansible.com/u/Jesse_Keating)\ **Post date:** [May 16, 2015, 8:59pm UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/5 "2015-05-16T20:59:53Z")
Please add a check for documenting module return data. That functionality was added recently and is extremely helpful for designing playbooks. - jlk ---
**Author:** ![Greg\_DeKoenigsberg1](https://avatars.discourse-cdn.com/v4/letter/g/838e76/32.png) [@Greg\_DeKoenigsberg1](https://forum.ansible.com/u/Greg_DeKoenigsberg1)\ **Post date:** [May 16, 2015, 10:04pm UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/6 "2015-05-16T22:04:33Z")
Perhaps someone would be willing to put together a first cut of this as a PR to the [contrib.md](http://contrib.md) for Extras? ---
**Author:** ![Brian\_Coca](https://avatars.discourse-cdn.com/v4/letter/b/6de8d8/32.png) [@Brian\_Coca](https://forum.ansible.com/u/Brian_Coca)\ **Post date:** [May 18, 2015, 12:54pm UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/7 "2015-05-18T12:54:35Z")
[https://github.com/ansible/ansible/pull/11027](https://github.com/ansible/ansible/pull/11027) ---
**Author:** ![Hank\_Beatty](https://avatars.discourse-cdn.com/v4/letter/h/f6c823/32.png) [@Hank\_Beatty](https://forum.ansible.com/u/Hank_Beatty)\ **Post date:** [June 25, 2015, 1:03am UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/8 "2015-06-25T01:03:59Z")
Hello Brian, I'm working on an iDRAC module and using 'action' for the wsman action to be taken on the iDRAC. I was eventually planning on submitting the module for inclusion in extras. Would the fact that I am using 'action' in this way prevent the module from being included? Thanks, Hank ---
**Author:** ![Brian\_Coca](https://avatars.discourse-cdn.com/v4/letter/b/6de8d8/32.png) [@Brian\_Coca](https://forum.ansible.com/u/Brian_Coca)\ **Post date:** [June 26, 2015, 3:31am UTC](https://forum.ansible.com/t/rfc-module-conventions-check-list/18245/9 "2015-06-26T03:31:46Z")
Hi Hank, We try to avoid having imperative language in the options, we prefer a declarative syntax, we do have modules that violate this rule but we would like to start enforcing it better now. That said, if you can make a good case why it should stay 'action' we are willing to listen. In the end, the change to the docs and spec is normally trivial.