Writing convention

In the Technique

  • We try to follow CFEngine conventions but with some exceptions like using brackets "{}" instead of parenthesis "()"
  • When defining bundles or bodies, the opening bracket should be on a dedicated line. Exemple:
bundle common control
{
  bundlesequence => { "exemple" };
}
  • Indentation should be made by spaces. A incrementation of indentation is equal to two spaces
  • The promise type should be indented by two spaces (instead of being at the same indentation level than the bundle name)
  • The class expression should be indented by four spaces (two spaces after the promise type)
  • The promiser should be indented by six spaces (two spaces after the class expression or four spaces after the promise type if no class expression is defined)
  • Attributes of promises should be indented by eight spaces (two spaces after the promiser) and it should be only one attribute by line.
  • Attribute’s arrows should all be at the same level, one character after the largest attribute name
bundle agent example
{
  type:
      "promiser"
        attribute  => "value1";

    class::
      "promiser2"
        attribute2 => "value2";
}
  • Attributes of promise type "vars" and "classes" should be on only one line except if there are more than one attribute.
  • For promise type "vars" and "classes" on one line, attribute names and the arrows should be aligned
  • A list should be written multilines if it needs more than 80 characters in one line
  • Multilines list should have comma after each element, except the last one.
  • Multilines list should begin with only a bracket "{"
    vars:
        "value" slist =>
          {
            "one",
            "two",
            "three"
          };
  • The name of the variable in argument of the bundle should be named "params"
  • The call of the variables should be made with by using brackets ${var_correctly_called} instead of parenthesis $(var_wrongly_called)
  • Alternance of brackets and parenthesis are tolerated when lots of variables are imbricated for more readability: ${var_lv1[$(var_lvl2[${var_lvl3}])]}
  • A Technique should have its bundle wrote with parameters
  • All the bundles should have as first argument "prefix" which contains the prefix to use for all the classes made from an outcome. This prefix should never be hardcoded in the bundle.
  • Always write comments with # when a promise needs more than 30 seconds of thought.
  • If classes should be created in order to iterate for make a workaround of the normal ordering (i.e: "iteration_1", "iteration_2", "iteration_3"), they should always be defined at the end of the promise type "classes".
  • The order to the promise type must always be in the order of the normal ordering : https://docs.cfengine.com/docs/3.10/reference-language-concepts-normal-ordering.html
  • StringTemplate variables should always be written in UPPERCASE
  • StringTemplate variables should be written with underscore
  • StringTemplate variables should always be prefixed by the Technique name in uppecase too. i.e: CHECK_GENERIC_FILE_FILE_NAME

In the metadata.xml

  • Name of sections should always be written in literary English (no CamelCase or underscores).
  • The value of variable "Don’t change" should always be "dontchange" or "" if the easier.