Coding Conventions

This section describes conventions, which you are advised to apply.

Requirement Levels - Wording

  • Shall: This word, or the terms "Mandatory", "Required" or "Must", mean that the rule or convention is an absolute requirement.

  • Shall not: This word, or the terms "Must not" mean that the rule or convention is an absolute prohibition.

  • Should: This word, or the adjective "Recommended", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

  • Should not: This phrase, or the phrase "Not recommended" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

  • May: This word, or the adjective "Optional", mean that an item is truly optional.

See also "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels".

Usage of static fields

You shall not use any static fields in your script code or other written classes inside of your project. Except static final constants of simple immutable types like (normally compile time constants):

  • int

  • boolean

  • double

  • String

  • …​

Static fields will cause memory leaks, because the fields are not garbage collected. Example:

scriptTask("Name") {
    code {
        MyClass.leakVariable.add("Leaked Memory")
    }

}

class MyClass {
    static List leakVariable = []
}

The use of static fields of the AutomationInterface is not allowed.

Usage of Outer Closure Scope Variables

The same static field rule applies to variables passed from outer Closure scopes into a script task code{} block. You shall not cache/save data into such variables.

Example:

scriptTask("Name") {
    def invalidVariable = [] //List

    code {
        invalidVariable.add("Leaked Memory")
    }

}

States over script task execution

You shall not hold or save any states over multiple script task executions in your classes.

The script task should be state less. All states are provided by the Automation API or the data models.

If you need to cache data over multiple executions, see the Stateful Script Tasks section for a solution.

Multithreading Support

A script task shall not create any Thread, Executor, ThreadPool or ForkJoinPool instances. Multithreading in automation scripts is not supported. Using multiple threads in automation scripts may lead to unexpected side effects, such as issues with live logging and debugging. If parallel execution is needed, different script tasks can be executed using multiple CLI instances.

Usage of DaVinci Configurator private Classes Methods or Fields

A script task should not call or rely on any non published API or private (also package private) classes, methods or fields. You also should not use any reflection techniques to reflect about Configurator internal APIs. Otherwise it is not guaranteed that your script will work with other DaVinci Configurator versions. See the PublishedApi section for details about the PublishedApi annotation.

But it is valid to use reflection for your own script code.