Module design practices

Sections

Consistent module design practices makes module contributions easier.

Spacing, indentation, and whitespace

Module manifests should follow best practices for spacing, indentation, and whitespace.

Manifests:

  • Must use two-space soft tabs.
  • Must not use literal tab characters.
  • Must not contain trailing whitespace.
  • Must include trailing commas after all resource attributes and parameter definitions.
  • Must end the last line with a new line.
  • Must use one space between the resource type and opening brace, one space between the opening brace and the title, and no spaces between the title and colon.
    Good:
    file { '/tmp/sample':
    Bad: Space between title and colon:
    file { '/tmp/sample' :
    Bad: No spaces:
    file{'/tmp/sample':
    Bad: Too many spaces:
    file     { '/tmp/sample':
  • Should not exceed a 140-character line width, except where such a limit would be impractical.

  • Should leave one empty line between resources, except when using dependency chains.

  • May align hash rockets (=>) within blocks of attributes, one space after the longest resource key, arranging hashes for maximum readability first.

Arrays and hashes

To increase readability of arrays and hashes, it is almost always beneficial to break up the elements on separate lines.

Use a single line only if that results in overall better readability of the construct where it appears, such as when it is very short. When breaking arrays and hashes, they should have:
  • Each element on its on line.

  • Each new element line indented one level.

  • First and last lines used only for the syntax of that data type.

Good: Array with multiple elements on multiple lines:
service { 'sshd':
  require => [
    Package['openssh-server'],
    File['/etc/ssh/sshd_config'],
  ],
}
Good: Hash with multiple elements on multiple lines:
$myhash = {
  key       => 'some value',
  other_key => 'some other value',
}
Bad: Array with multiple elements on same line:
service { 'sshd':
  require => [ Package['openssh-server'], File['/etc/ssh/sshd_config'], ],
}
Bad: Hash with multiple elements on same line:
$myhash = { key => 'some value', other_key => 'some other value', }
Bad: Array with multiple elements on different lines, but syntax and element share a line:
service { 'sshd':
  require => [ Package['openssh-server'],
    File['/etc/ssh/sshd_config'],
  ],
}
Bad: Hash with multiple elements on different lines, but syntax and element share a line:
$myhash = { key => 'some value',
  other_key     => 'some other value',
}
Bad: Array with idention of elements past two spaces: 
service { 'sshd':
  require => [
              Package['openssh-server'],
              File['/etc/ssh/sshd_config'],
  ],
}

Quoting

As long you are consistent, strings may be enclosed in single or double quotes, depending on your preference.

A string does not have to be in single quotes if it:
  • Contains variables.

  • Contains single quotes.

  • Contains escaped characters not supported by single-quoted strings.

  • Is an enumerable set of options, such as present/absent, in which case the single quotes are optional.

Enclose all variables in braces when interpolated in a string.

For example:

Good:
"/etc/${file}.conf"
"${facts['operatingsystem']} is not supported by ${module_name}"
Bad:
"/etc/$file.conf"
"$facts['operatingsystem'] is not supported by $module_name"
When a string contains single quotes, enclose it in double quotes, rather than using escape-character single quotes, unless doing so would require an inconvenient amount of additional escape characters.
Good:
warning("Class['apache'] parameter purge_vdir is deprecated in favor of purge_configs")
Bad:
warning('Class[\'apache\'] parameter purge_vdir is deprecated in favor of purge_configs')

Escape characters

Use backslash (\) as an escape character.

For both single- and double-quoted strings, escape the backslash to remove this special meaning: \\ This means that for every backslash you want to include in the resulting string, use two backslashes. As an example, to include two literal backslashes in the string, you would use four backslashes in total.

Do not rely on unrecognized escaped characters as a method for including the backslash and the character following it.

Unicode character escapes using fewer than 4 hex digits, as in \u040, results in a backslash followed by the string u040. (This also causes a warning for the unrecognized escape.) To use a number of hex digits not equal to 4, use the longer u{digits} format.

Comments

Comments must be hash comments (# This is a comment). Comments should explain the why, not the how, of your code.

Do not use /* */ comments in Puppet code.

Good:
# Configures NTP
file { '/etc/ntp.conf': ... }
Bad:
/* Creates file /etc/ntp.conf */
file { '/etc/ntp.conf': ... }
Note: Include documentation comments for Puppet Strings for each of your classes, defined types, functions, and resource types and providers. If used, documentation comments precede the name of the element. For documentation recommendations, see the Modules section of this guide.

Functions

Avoid the inline_template() and inline_epp() functions for templates of more than one line, because these functions don’t permit template validation. Instead, use the template() and epp() functions to read a template from the module. This method allows for syntax validation.

You should avoid using calls to Hiera functions in modules meant for public consumption, because not all users have implemented Hiera. Instead, we recommend using parameters that can be overridden with Hiera.

How helpful was this page?
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.