When must named arguments be used in function calls?

← Code Quality · Ref: Q694

EK9 requires named arguments in two situations: when a call passes 2 or more Boolean LITERALS positionally, and when a call passes 4 or more arguments.

BOOLEAN POSITIONAL LITERALS (E11061)

Two or more Boolean literals in one call are ambiguous when positional:

  setMode()
    ->
      verbose as Boolean
      debug as Boolean
    <- rtn as String: `verbose=${verbose} debug=${debug}`

  stdout <- Stdout()
  stdout.println(setMode(true, false))                  // ERROR E11061: which is which?
  stdout.println(setMode(verbose: true, debug: false))  // Correct: named

A single positional Boolean literal (formatOutput("hello", true)) is accepted, and so are Boolean variables passed positionally (setMode(verboseOn, debugOff)) - the variable names already say what they mean. Naming a single Boolean literal is still clearer.

4+ POSITIONAL ARGS (E11062)

A call that passes 4 or more arguments positionally is rejected - name them:

  configure()
    ->
      host as String
      port as Integer
      secure as Boolean
      user as String
    <- rtn as String: `${user}@${host}:${port} secure=${secure}`

  stdout <- Stdout()
  stdout.println(configure("db", 8080, true, "admin"))                         // ERROR E11062
  stdout.println(configure(host: "db", port: 8080, secure: true, user: "admin"))  // Correct

WHY THIS MATTERS

Named arguments make call sites self-documenting. Without names, readers must look up the function signature to understand what each argument means.

FEWER ARGS OK

A call with 1-3 arguments can be positional, as long as it does not pass 2 or more Boolean literals:

  greet("Alice", "morning")  // OK: only 2 args

See Q314 for naming conventions. See Q322 for code quality metrics. See Q689 for boolean condition patterns.

Example

defines module qa.codequality.namedarguments

  defines function

    <?-
      Function with 4+ parameters.
      Callers MUST use named arguments.
    -?>
    createConnection()
      ->
        hostName as String
        portNumber as Integer
        useTls as Boolean
        connectionTimeout as Integer
      <- connectionInfo as String: `${hostName}:${portNumber} timeout=${connectionTimeout}`

      if useTls
        connectionInfo: connectionInfo + " TLS"

    <?-
      Function with fewer parameters: positional OK.
    -?>
    formatGreeting() as pure
      ->
        recipientName as String
        greeting as String
      <- message as String: `${greeting}, ${recipientName}!`

    <?-
      Function with a Boolean parameter: a single Boolean literal may be positional,
      but naming it is clearer.
    -?>
    formatOutput() as pure
      ->
        content as String
        includeTimestamp as Boolean
      <- formatted as String: content

      if includeTimestamp
        formatted: "[timestamp] " + content

  defines program

    NamedArgumentsPatternDemo()
      stdout <- Stdout()

      //4+ params: named arguments required
      connInfo <- createConnection(hostName: "db.example.com", portNumber: 5432, useTls: true, connectionTimeout: 30)
      stdout.println(connInfo)

      //2 non-Boolean params: positional OK
      greeting <- formatGreeting("Alice", "Good morning")
      stdout.println(greeting)

      //Boolean param: named argument is clearer (required only for 2+ Boolean literals)
      output <- formatOutput(content: "hello", includeTimestamp: true)
      stdout.println(output)

Common mistakes

E50060 — String has no toUpperCase() method in EK9. Use upperCase() instead. See ek9 -h E50060 for details.

Incorrect:

stdout.println(output.toUpperCase())

Correct:

stdout.println(output)

E50060 — String has no toString() method in EK9. The variable is already a String. See ek9 -h E50060 for details.

Incorrect:

stdout.println(connInfo.toString())

Correct:

stdout.println(connInfo)

Other ways to ask this

What is E11061 boolean positional argument?
What is E11062 too many positional arguments?
When are named arguments required in EK9?
How do I use named arguments for clarity?

Coming from another language?

Java: no named argument support. Python: named arguments optional. Kotlin: named arguments optional but encouraged. Swift: named arguments required by default. Go: no named arguments. EK9: named arguments mandatory for calls with 4+ arguments (E11062) and for 2+ positional Boolean literals (E11061).

Keywords: function, named, Boolean, clarity, E11061, E11062, arguments, quality, metric, parameter, clean-code, positional