Skip to content

Commit 9ec4062

Browse files
committed
Add a concrete Optional[T] = undef example to the style guide
Illustrate the "Optional parameters" guidance with chrony's smoothtime parameter: declared Optional[String] = undef, and emitted in the config template only when a value is set, so undef genuinely means the optional feature is off. Signed-off-by: Michael Harp <mike@mikeharp.com>
1 parent 020f8a0 commit 9ec4062

1 file changed

Lines changed: 16 additions & 0 deletions

File tree

docs/_openvox_8x/style_guide.markdown

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -963,6 +963,22 @@ Under this guidance, parameter defaults rarely belong in `common.yaml`: a static
963963

964964
Reserve `Optional[T] = undef` for parameters where `undef` is a genuine runtime value, such as a parameter that switches an optional feature off. In that case, `undef` is a meaningful state the user can select.
965965

966+
For example, chrony's `smoothtime` parameter is declared `Optional[String] $smoothtime = undef`:
967+
968+
```puppet
969+
Optional[String] $smoothtime = undef,
970+
```
971+
972+
and its config template emits the directive only when a value is set:
973+
974+
```text
975+
<% if $chrony::smoothtime { -%>
976+
smoothtime <%= $chrony::smoothtime %>
977+
<% } -%>
978+
```
979+
980+
Here `undef` genuinely means the feature is off, so `Optional[T] = undef` is the right choice.
981+
966982
Avoid declaring a parameter `Optional` just to defer its default to Hiera when the parameter will always receive a value. Doing so misleads users into thinking `undef` is a supported state when it isn't, and it weakens the type assertion. Declare the real type and give the parameter its actual default instead.
967983

968984
### Exported resources

0 commit comments

Comments
 (0)