社内向け技術文書 コーディング規約

Puppet manifest 独自コーディング規約

社内向け技術文書 コーディング規約

manifestのコーディング規約を決めとこう。

基本的には本家のここに従う。Style Guide

いくつか気になるのをピックアップすると。

  • リソースパラメータのデフォルト値はトップレベルスコープにしか置かない(各クラス内で設定しない)。

9.7. Resource Defaults

Resource defaults should be used in a very controlled manner, and should only be declared at the edges of your manifest ecosystem. Specifically, they may be declared:

At top scope in site.pp In a class which is guaranteed to never declare another class and never be inherited by another class.

   This is due to the way resource defaults propagate through dynamic scope, which can have unpredictable effects far away from where the default was declared.
  • トップレベルの変数をmodule内で使うときは$::をつける

11.6. Namespacing Variables

When using top-scope variables, including facts, Puppet modules should explicitly specify the empty namespace (i.e., $::operatingsystem, not $operatingsystem) to prevent accidental scoping issues.

  • 変数にハイフンを使わない

11.7. Variable format

When defining variables you should only use letters, numbers and underscores. You should specifically not make use of dashes.

  • classのネストや、class内でのdefined resource定義をしない

11.4. Classes and Defined Resource Types Within Classes

Classes and defined resource types must not be defined within other classes.

ペパボ独自規約

予約語となっているパラメータ引数はクオートしない

Good:

file { '/tmp':
  ensure => directory,
}

Bad:

file { '/tmp':
  ensure => "directory",
}

同一タイプリソースの間に空行

パラメータが多いと、複数並んだ時に見づらいため、一行空けます。

Good:

file {
  '/foo/baa':
    source  => 'puppet:///foo/baa',
    mode    => '0644',
    require => File['/foo'];

  '/aaa/bbb':
    content => template('aaa/bbb'),
    mode    => '0755';
}

Bad:

file {
  '/foo/baa':
    source  => 'puppet:///foo/baa',
    mode    => '0644',
    require => File['/foo'];
  '/aaa/bbb':
    content => template('aaa/bbb'),
    mode    => '0755';
}

複数requireで改行

複数の要素を横に並べると、あとから編集しにくくなるので改行をいれます。

Good:

sevice { 'mydaemon':
  ensure  => running,
  require => [
    Package['mydaemon'],
    File['mydaemon.conf'],
  ]
}

Bad:

sevice { 'mydaemon':
  ensure  => running,
  require => [
    Package['mydaemon'], File['mydaemon.conf'],
  ]
}

include は1つずつ

横に並べない。includeの順はそれなりに処理順でもあるので、横並びだと、順番を変えたい時に編集がめんどうです。

Good:

include base
include base::config
include base::packages

Bad:

include base, base::config, base::packages

Relationship Declarationsのインデント

縦方向に整列することで読みやすくする。

Good:

   Class['hoge']
-> Class['hoge::install']

Not Good:

Class['hoge']
-> Class['hoge::install']

sourceを指定したfileリソースの ensure => file は不要

sourceやcontentで内容まで管理しているfileリソースの場合、ファイル名や拡張子で、 それが一般ファイルであることが明白である場合は、ensure => file での明示は不要です。

Good:

file { '/tmp/hoge.txt':
  source => 'puppet:///modules/hoge/tmp/hoge.txt',
}

Not Good:

file { '/tmp/hoge.txt':
  ensure => file,
  source => 'puppet:///modules/hoge/tmp/hoge.txt',
}

directoryは必ず ensure => directory を明示する

fileリソースで管理する対象がdirectoryの場合は、必ずensure => directory で明示します。

Good:

file { '/etc/hoge':
  ensure  => directory,
  source  => 'puppet:///modules/hoge/etc/hoge',
  recurse => true,
}

Bad:

file { '/etc/hoge':
  source  => 'puppet:///modules/hoge/etc/hoge',
  recurse => true,
}