5. Plugin formatting

5a. Formatting

Ferrite plugins have their own subjective formatting guidelines for consistency. The rules are as follows:

• All indentation must be 2 spaces, similar to any other YAML file.

• Follow YAML implicit typing when possible.

• Strings must be single quoted if the implicit type is not properly inferred.

  • # Good
    example: 'The quick brown fox jumps over the lazy dog'
    
    # Bad
    example: "The quick brown fox jumps over the lazy dog"

• Multiline arrays must use YAML block-style sequences for readability.

  • Note: Flow style can be used if the elements are short, but they are not recommended due to cluttering readability.

  • # Good
    mysequence:
      - First
      - Second
      - Third
    
    # Bad
    mysequence:
    - First
    - Second
    - Third
    
    # Bad (flow style)
    mysequence: [First, Second, Third]

• Comments must not clutter the source file and enhance readability.

  • # Good
    
    # This is a good top comment
    myblock:
      - name: My name
        status: Alive # This is a good side comment
      - name: My second name
        status: Alive
    
    # Bad
    
    myblock:
    # This is a bad top comment
      - name: My name
        # This is a bad inline top comment
        status: Alive
      - name: My second name
        status: Alive

• Do not use newline characters \n when creating YAML strings, instead use operators such as |, |-, >, or >- which automatically create newlines for you. The - character removes the last newline on a string which is preferred!

  • # Literal operators (| and |-)
    # Newlines are preserved on this string!
    example: |-
        Hi, my name is kingbri.
        Ferrite is a great application used for many things
    
    # Folded operators (> and >-)
    # All newlines are removed from this string!
    example: >-
        Hi, my name is kingbri.
        Ferrite is a great application used for many things