Coding conventions

This Ballerina Style Guide aims at maintaining a standard coding style among the Ballerina community. Therefore, the Ballerina code formatting tools are based on this guide.

Indentation and line length

  • Use four spaces (not tabs) for each level of indentation.
  • Keep the maximum length of a line to 120 characters.

Note: You can configure tools and plugins to use spaces when indenting and to change the maximum number of characters in a line.

Line spacing

  • Use only a single space to separate keywords, types, and identifiers.

Do's

public function getFullName() returns string {
    string fullName = "john doe";
    return fullName;
}

Don'ts

public   function   getFullName()   returns   string {
    string   fullName = "john doe";
    return     fullName;
}

Few exceptions for this rule are:

  • Do not keep spaces around a type when it is enclosed using angle brackets <string>.

Example,

map<string> names = {};
  • Do not keep spaces between the type and the opening bracket in the array definition string[].

Example,

string[] names = [];
  • If it is a list of values separated by commas, add only a single space after each comma and don't add spaces before the comma.

Example,

[string, int, boolean] tupleVar = ["", 0, false];

int[] arrayOfInteger = [1, 2, 3, 4];

map<string> stringMap = {one: st1, two: st2, three: st3};

Person personRecord = {name: "marcus", id: 0};

function foo(string name, int id) {
}
    
service / on ep1, ep2 {
    ...
}

Blank lines

Separate both statements and top-level definitions by zero or one blank lines.

Example,

import ballerina/http;
import ballerina/io;

const string CITY = "Colombo";
const int CITY_NO = 1;

function getName() returns string {
    string firstName = "john";
    string lastName = "doe";

    return firstName + lastName;
}

function setName(string name) {
}

function setAge(int age) {
}

Blocks

  • Opening curly braces of a block should be placed inline.

Do's

if true {
}
  
function setName(string name) {
    ...
}

Don'ts

if true
{
    
}

function setName(string name)
{
  
}
  • Add a single space before the opening curly braces.

Example,

function func1() {
    if true {
    }
}
  • If an inline block is empty, do not keep spaces in between the opening and closing braces.

Example,

function func1() {
}
  • Indent all the statements inside a block to be at the same level.
  • Indent the closing brace of a block to align it with the starting position of the block statement.

Example,

if false {
   int x = 2;
   string a = "hello";
}
  
match a {
   ...
}

Parentheses and brackets

  • Do not have spaces after opening parenthesis/bracket and before closing parenthesis/bracket.

Example,

[string, int] tupleVar = ["", 0];

function setValue(string value) {
    ...
}

public function main() {
    setValue("value");
}
  • To define empty parentheses/brackets, do not keep spaces between the opening and closing parentheses/brackets. i.e. () ,[].

Example,

int[] a = [];
int|() result = getResult();

Line breaks

  • Have only one statement in a line.
  • When splitting lines, which contain operator(s), split them right before an operator.

Example,

// Binary operations.
string s = "added " + People.name
    + " in to database.";
  
// Function invocation.
string s = person
    .getName();
  
// Binary operations in if condition
if isNameAvailable
    && (i == 1) {
    ...
}
  • When splitting lines, which contains separator(s), split them right after a separator.

Example,

// Function parameters.
function getName(int id, int age,
    string searchValue) returns string {
    ...
}
  • If there isn't any operator or separator to break the line from, move the whole expression to a new line.

Example,

// String literal.
string s1 =
    "My name is not in this description";
  
// Function invocation.
string s2 =
    getPersonNameWithUpperCaseLetters();
  • If a line exceeds the maximum line length, start from the end of the line and come towards the start of the line until you find a point, which matches the above rules to break the line.
  • Indent split lines with relation to the starting position of the statement or definition.

Example,

if isNameAvailable
    && (i == 1) {
    ...
}
  
// Function parameters.
function getName(int id, int age,
    string searchValue) returns string {
    ...
}
  • However, if you cannot add the type-casting expression or statement with the constrained type in a single line due to it exceeding the max line length,
    • move the casting type with the operators to a new line.

Example,

string name =
    <string>person.name;
  • keep the constrained type on the same line by splitting the statement from a point before the constraint type.

Example,

map<int|string> registry = {
    name: "marcus"
};