Use a style guide to make it easier to update and maintain code

One of the most common questions from the Puppet community is, "What’s the best way to write a module/class/resource? What style does Puppet use to write manifests?"

What is a style guide?

A style guide outlines expectations that give Puppet code a standardized look and feel. It promotes consistent formatting in the Puppet language, giving you a common pattern, design, and style to follow when developing modules. This consistency in code and module structure makes it easier to update and maintain code.

Why is a style guide important?

We’ve all been there. Each person has a unique style. Every team does things differently. Server builds and code look like spaghetti. It takes forever to understand the intent of the author or sysadmin.

A style guide helps code contributors and administrators to code and manage systems consistently. Time to resolve and troubleshoot problems decreases. Code is easier to navigate. Everyone is able to contribute code using the same style.

Puppet language style guide

When your Puppet code is consistent with the Puppet language style guide, onboarding new developers is simplified.

The Puppet language style guide covers visual style, form, and ways to create resources, classes, and modules. You can validate against the Puppet style guide with puppet-lint and the Puppet Development Kit (PDK).

Can we just use Puppet’s style guide?

You can, but we suggest that you also create an internal style guide that references the Puppet language style guide. Puppet’s style guide covers most things. However, it doesn’t cover which design patterns to use, what naming conventions to use, and your organization’s preferences.

To align all of your contributors, include these things in your style guide:

• Adhere to the official Puppet language style guide.

• Naming conventions for custom modules, custom facts, functions, and other code.

• Specific design patterns that you wish to use, such as the site.pp pattern or the roles and profiles pattern.

• Decisions and preferences that are specific to your organization’s Puppet infrastructure.

• Decisions about how your code is organized. For example, you might want to put all custom facts in a module such as myorg-customfacts so they are in one place. Or, you might want to create a library frequently reused functions in a module such as myorg-myorglibs module.