Add a subsection under the top level definition in style guides to specify constant declaration best practices

[LakshanWeerasinghe]

Description

In the style guides page under the top level definitions section we don't have a section cover the best practice when declaring constant values. Even in the general practices subsection we have constant declaration without using the best practice.

In the spec it is optional to add the type-descriptor when declaring constant values. When the type-descriptor is not present the type checker will resolve the expressions singleton type and add it as the constant type. Also when we don't have the type descriptor present in the constant declaration we don't have to do a additional type checking.

The only place we need to add the type-descriptor is the cases where we need to explicitly cast as a literal value. I think we can mention that.
eg:

const decimal VALUE = 1.2;

Related website/documentation area

Describe the problem(s)

A detailed description of the purpose of this improvement.

Describe your solution(s)

A detailed description of how this improvement will solve the problem described above.

Related issue(s) (optional)

Any related issues such as sub tasks and issues reported in other repositories (e.g., component repositories), similar problems, etc.

Suggested label(s) (optional)

Optional comma-separated list of suggested labels. Non committers can’t assign labels to issues, and thereby, this will help issue creators who are not a committer to suggest possible labels.

Suggested assignee(s) (optional)

Optional comma-separated list of suggested team members who should attend the issue. Non committers can’t assign issues to assignees, and thereby, this will help issue creators who are not a committer to suggest possible assignees.

[anupama-pathirage]

@hasithaa / @MaryamZi can we add this to update 9 related doc updates?

[lochana-chathura]

Now that we support the type descriptor in the module-const-decl, I would like to consider the following points when deciding the best practice for the module-constant-decl

1. Type Safety: Explicitly declaring the type of a constant can enhance type safety. It ensures that the constant will always have a specific type, reducing potential errors due to type mismatches.

2. Readability: Explicit type declaration can improve code readability. It makes it clear to anyone reading the code what type the constant is expected to be.

3. Inference: Assuming our type checker has a strong type inference mechanism and can accurately determine the type of a constant from its initial value, it might be unnecessary to explicitly declare the type.

Consider the below code.

const string REPO_NAME = "balleirna-lang";
const REPO_NAME = "balleirna-lang";

• Based on point 2, I was kind of prefer having the type explicitly (may be also because in java it is always written as stiatic final string REPO_NAME = "ballerina-lang" with the type :-P). However, second option may be short and sweet.

• This could also compare against, having var vs the actual type in the variable-decl

var REPO_NAME = "balleirna-lang";
string REPO_NAME = "balleirna-lang"; // We prefer this becuase of point 2.

• We could also consider expressions where the resultant constant value is not so obvious at a glance.

In the following case based on 1 and 2 points, I think it is better to explicitly declare the type.
e.g.

// Having the explicit type here would make sure 
// the user can use this constant in a place where a byte is expected 
// without having much thought.
const byte FOO_VAL = 7 * 25 + 79; 

[prakanth97]

According to the spec, If type-descriptor is present, then it provides the contextually expected type for the interpretation of const-expr.

Hence type descriptor is only useful for cases such as

const decimal VAL_1 = 1;

when we have to decide the type of literals.

Also spec says, The type of the constant is the intersection of readonly and the singleton type containing just the shape of the value named by the constant

IMO, expected type is only required for when we have to modify the default behaviour such as mentioned before. It is better to not use the expected type and it will reduce the unnecessary type checking as well.

[MaryamZi]

Even

const decimal VAL_1 = 1;

we can write as

const VAL_1 = 1d;

Given that using the type-descriptor isn't used as the inherent type, I also prefer omitting the type, unless it's actually required for construction.

1. Type Safety: Explicitly declaring the type of a constant can enhance type safety. It ensures that the constant will always have a specific type, reducing potential errors due to type mismatches.

2. Readability: Explicit type declaration can improve code readability. It makes it clear to anyone reading the code what type the constant is expected to be.

What the type-descriptor would say is that the constant's type is a subtype of that type, rather than the exact type. So, I'm not sure these make a significant difference. In fact, it may even make it clearer to the user that the type of the constant is a singleton.

• This could also compare against, having var vs the actual type in the variable-decl

var REPO_NAME = "balleirna-lang";
string REPO_NAME = "balleirna-lang"; // We prefer this becuase of point 2.

IMO, using var here is OK. What we usually discourage is something like

var result = getResult();

where it's not obvious without looking at getResult what the type is.

Unless we need something from the type-descriptor (and maybe some complicated expressions), I think we can recommend defining the constant without the type.

[lochana-chathura]

Thanks for the input.

[lochana-chathura]

// don't
const map<int> MAX_DIMENSION_SIZES = {width: 1920, height: 1080};
const string[] DAYS_OF_WEEK = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];

// do
const MAX_DIMENSION_SIZES = {width: 1920, height: 1080};
const DAYS_OF_WEEK = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];

I was writing the above samples. However, for the first one, if we use a record say,

record {| int width; int height;|}

Then it would be easy to access the width and height from the constant neh.
e.g.

MAX_DIMENSION_SIZES.height
MAX_DIMENSION_SIZES.width

In that case, I prefer to have the record as the type descriptor depends on the usecase. WDYT? @MaryamZi @prakanth97

// don't
const map<int> MAX_DIMENSION_SIZES = {width: 1920, height: 1080};

// do
const MAX_DIMENSION_SIZES = {width: 1920, height: 1080};
// or 
const record {| int width; int height;|} MAX_DIMENSION_SIZES = {width: 1920, height: 1080};