Annotations

• Do not have spaces around the @ symbol.

• Indent annotations to align them with the starting position of the owner (statement or definition).

• Each annotation attribute (i.e., key-value pairs) can be expanded and block indented on its own line or kept as inline fields.

  Example,

  // Function annotations are aligned with the starting position of the function.
  @test:Config {
      before: beforeFunc,
      after: afterFunc
  }
  function testFunction() {
      io:println("I'm in test function!");
      test:assertTrue(true, msg = "Failed!");
  }

• If an annotation is empty, place it in a single line and do not have spaces between both braces.

  Example,

  @test:Config

• If you are annotating a parameter or a return type, the annotation should be added inline to the parameter or the return type.

  Example,

  annotation validated on parameter, return;
  
  // Parameter annotation.
  public function secureFunction1(@validated string secureInName, int secureInId, string insecureIn) {
      ...
  }
  
  public function secureFunction2(string secureInName,
      @validated int secureInId, string insecureIn) {
      ...
  }
  
  // Return type annotation.
  public function taintedReturn1() returns @validated string {
      ...
  }
  
  public function taintedReturn2() returns
      @validated string {
      ...
  }

Comments

• Add a single space between the // and the content.

• If the comment is in its own line, then indent it considering its context (i.e., top-level or in a block).

  Example,

  // This is a top-level comment.
  
  function func1() {
      // This is a block-level comment. 
      int x = 10;
  }
  
  function func2() {
      if valid {
          if active {
              // This is a nested if block-level comment.
              string a = "hello";
          }
      }
  }

• If the comment is in line with the code, add a space before it.

  Example,

  type People record {}; // Inline comment
  
  function func1() {
      int a = 0; // Inline comment
  }

Documentation

• Always, indent them to align with the starting position of the owner.

• Add a space after the # symbol.

• Add an empty line after the description.

  Example,

  # Description.
  #
  # + value - value input parameter 
  # + return - return a integer value
  function getValue(int value) returns int {
      return value;
  }

• Add only one space after the parameter marker (+), divider (-), and return.

• Begin the param identifier and description with a single space.

  Example,

  # Description.
  #
  # + value - Parameter description
  # + return - Return value description
  function getValue(int value) returns int {
      ...
  }
  
  # Description.
  service / on new http:Listener(8080) {
      # Description.
      #
      # + caller - Parameter description.
      # + request - Parameter description.
      resource function get greeting(http:Caller caller, http:Request request) {
          ...
      }
  }

• For record type definitions add the description above the type definition.

• Similarly, for each field add the description above the field definition.

• Don't leave empty lines between the description and the corresponding definition.

  Example,

  # Represents a user.
  type User record {|
      # Id of the user
      int id;
      # Name of the user
      string name;
      # Whether the user is a member
      boolean isMember;
  |};

• If the fields have annotations, you could introduce empty lines in between field definitions to improve readability.

  Example,

  # Represents a user with metadata.
  type UserWithMetadata record {|
      # Id of the user
      @constraint:Int {
          maxDigits: 10
      }
      int id;
  
      # Name of the user
      @constraint:String {
          minLength: 5,
          maxLength: 20
      }
      string name;
  
      # Address of the user
      @constraint:String {
          minLength: 20,
          maxLength: 100
      }
      string address;
  |};