Naming conventions

Following are the naming conventions used in various Ballerina constructs. Some are opinionated rules but ensure consistency.

Organizations

  • Organization names can only contain alphanumeric values with lowercase letters and cannot start with numeric values.
  • Organization names starting with ballerina (e.g., ballerina, ballerinax, ballerinai, etc.) are reserved for system use, and you cannot publish any packages starting with the ballerina prefix to Ballerina Central.

Bad Names

7eleven
Google
ballerinac

Good Names

wso2
google

Packages and modules

  • Names can only contain alphanumerics, underscores, and periods and the maximum length is 256 characters.
  • Names can contain alphanumeric characters, including dots. Dots in a module name has no meaning other than the last segment after the final dot is used as a default alias within the source code.
  • When a package provides multiple functionalities, it is better to split it into multiple packages. For scenarios like this, you can give a hierarchical name to the package by using a dot (.).

Bad Names

Auth
HTTP
aws_s3

Good Names

auth
http
aws.s3

Files

  • Ballerina source files should have the extension .bal always.
  • Ballerina file names should all be simple.
  • Has to start with a character, and if the file name has multiple words, those words should be separated by an underscore (_).

Bad Names

StockQuoteService.bal
stockQuoteService.bal

Good Names

listner.bal
stock_quote_service.bal

Functions

  • Function names must be verbs in camel case, starting with a lowercase letter (i.e., lowerCamelCase).
  • Function parameters must be in camel case starting with a lowercase letter (i.e., lowerCamelCase).
  • Abbreviations and acronyms must not be uppercase when used in function names.

Bad Names

function TotalWidth()
function AddStudent( int age, string FullName)
function buildRSAPublicKey()

Good Names

function computeTotalWidth()
function addStudent( int age, string fullName)
function buildRsaPublicKey()

Variables

  • Variable names must be in camel case, starting with a lowercase letter (i.e., lowerCamelCase).

Bad Names

int Count;
string accountname;
string account_name;

Good Names

int count;
string accountName;

Constants

  • Constants must be all uppercase, using underscore to separate words.

Bad Names

const MAXSIZE = 1000;
const maxSize = 1000;

Good Names

const MAX_SIZE = 1000;

Objects and records

  • All object and record names must be nouns in camel case starting with an uppercase letter.
  • All object and record fields must follow normal variable naming rules.

Bad Names

public type Employee_Data record {|
    string first_Name;
    string LastName;
    int age;
|};

Good Names

public type Employee record {|
    string firstName;
    string lastName;
    int age;
|};

Clients

  • Name it to reflect the type of the client.
  • Avoid unnecesary repetitive words such as Client.

Bad Names

twilio:Client myClient = check new ({twilioAuth: {accountSId, authToken}});
twilio:Client c = check new ({twilioAuth: {accountSId, authToken}});
twilio:Client twilioClient = check new ({twilioAuth: {accountSId, authToken}});

Good Names

twilio:Client twilio = check new ({twilioAuth: {accountSId, authToken}});

Names with Abbrevations

  • When using abbreviations in names, treat the abbreviation as another word.

Bad Names

public function hashMD5(byte[] input) {

}

type LLMModel record {|
    
|};

string originalSHAValue;

Good Names

public function hashMd5(byte[] input) {

}

type LlmModel record {|
    
|};

string originalShaValue;

REST Service and resource paths

  • The service path represents the absolute path to the service. If the service path is omitted, then it defaults to /. Use meaningful grouping name if it is not omitting.
  • Use lowercase letters.
  • Try to use simple single words, but when it is needed to have multiple words use dashes instead of underscore.

Bad Names

service /MusicStore on new http:Listener(9090) {

}

service "/music_store" on new http:Listener(9090) {

}

Good Names

service "/store" on new http:Listener(9090) {

}

service "/music-store" on new http:Listener(9090) {

}

OR the same can be done as follows.

service /music\-store on new http:Listener(9090) {

}
  • Use nouns instead of verbs for resource function names. Verbs should not be used in endpoint paths.

Bad Names

service / on new http:Listener(9090) {

    resource function get getAlbums() returns Album[] {

    }
}

Good Names

service / on new http:Listener(9090) {

    resource function get albums() returns Album[] {

    }
}
  • Use plural resource nouns.

Use the plural form for resource nouns, because this fits all types of endpoints.

Bad Names

service / on new http:Listener(9090) {

    resource function get albums() returns Album[] {
        return [{title: "title1", artist: "artist1"}, {title: "title2", artist: "artist2"}];
    }

    resource function get album/[string title]() returns Album {
        return {title: "title1", artist: "artist1"};
    }
}

Good Names

service / on new http:Listener(9090) {

    resource function get albums() returns Album[] {
        return [{title: "title1", artist: "artist1"}, {title: "title2", artist: "artist2"}];
    }

    resource function get albums/[string title]() returns Album {
        return {title: "title1", artist: "artist1"};
    }
}