From 2e1733bde76e0a8ad88ded66a4d03e8ef2e529ff Mon Sep 17 00:00:00 2001 From: lochana-chathura <39232462+lochana-chathura@users.noreply.github.com> Date: Wed, 10 Apr 2024 15:36:04 +0530 Subject: [PATCH 1/4] Add style guideline for `const-decl` best practices --- .../style-guide/top-level-definitions.md | 47 ++++++++++++++++++- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md index 05883e4f628..0406f00590e 100644 --- a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md +++ b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md @@ -15,7 +15,7 @@ intro: The sections below include the coding conventions with respect to top-lev ```ballerina import ballerina/http; - const int MIN_AGE = 20; + const MIN_AGE = 20; int repetitions = 0; service / on ep1 { @@ -29,7 +29,7 @@ intro: The sections below include the coding conventions with respect to top-lev // This import is indented correctly. import ballerina/http; - const int MIN_AGE = 20; // Not indented correctly. + const MIN_AGE = 20; // Not indented correctly. int repetitions = 0; // Not indented correctly. // Not indented correctly. @@ -50,6 +50,49 @@ intro: The sections below include the coding conventions with respect to top-lev * Imports should be sorted alphabetically, first by the organization name and then by the module name. +## Constant declaration + +* Use the SCREAMING_SNAKE_CASE for constant names. + + **Example,** + + ```ballerina + // don't + const minAge = 20; + const MinAge = 20; + const min_age = 20; + + // do + const MIN_AGE = 20; + ``` + +* It is recommended to define the constants omitting the type descriptor, unless the type descriptor is used as the inherent type. + + **Example,** + + ```ballerina + // don't + const int MIN_AGE = 20; + const decimal TAX_RATE = 0.15; + + // do + const MIN_AGE = 20; + const TAX_RATE = 0.15d; + ``` + +* It may be necessary to explicitly define the type descriptor when the constant is a complicated expression. + + **Example,** + + ```ballerina + // don't + const COMPLEX_VALUE = (50 * 2 + 100) % 256; + + // do + // The explicit `byte` type descriptor ensures this constant can be used where a `byte` is expected. + const byte COMPLEX_VALUE = (50 * 2 + 100) % 256; + ``` + ## Function definition * Do not keep spaces between the function name and the open parentheses `(` of the function signature. From 5f236e434e8850a330d14d3ae15065ec71fe106e Mon Sep 17 00:00:00 2001 From: lochana-chathura <39232462+lochana-chathura@users.noreply.github.com> Date: Wed, 10 Apr 2024 17:06:27 +0530 Subject: [PATCH 2/4] Refactor documentation based on review suggestions --- .../style-guide/top-level-definitions.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md index 0406f00590e..0139eeef3a0 100644 --- a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md +++ b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md @@ -66,7 +66,7 @@ intro: The sections below include the coding conventions with respect to top-lev const MIN_AGE = 20; ``` -* It is recommended to define the constants omitting the type descriptor, unless the type descriptor is used as the inherent type. +* It is recommended to define the constants without the type descriptor, unless the type descriptor is used as the inherent type. **Example,** @@ -80,7 +80,7 @@ intro: The sections below include the coding conventions with respect to top-lev const TAX_RATE = 0.15d; ``` -* It may be necessary to explicitly define the type descriptor when the constant is a complicated expression. +* Explicitly defining the type descriptor can enhance readability, particularly when the constant is defined with a compound expression. This practice provides clarity about the expected type. **Example,** @@ -89,7 +89,8 @@ intro: The sections below include the coding conventions with respect to top-lev const COMPLEX_VALUE = (50 * 2 + 100) % 256; // do - // The explicit `byte` type descriptor ensures this constant can be used where a `byte` is expected. + // The explicit `byte` type descriptor here improves readability. + // It ensures that `COMPLEX_VALUE` can be safely used wherever a `byte` is expected. const byte COMPLEX_VALUE = (50 * 2 + 100) % 256; ``` From 2dc1e329e019543ccdc3912d3564802b8b9435a8 Mon Sep 17 00:00:00 2001 From: lochana-chathura <39232462+lochana-chathura@users.noreply.github.com> Date: Tue, 16 Apr 2024 13:37:45 +0530 Subject: [PATCH 3/4] Replace comma with colon in 'Example,' --- .../style-guide/top-level-definitions.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md index 0139eeef3a0..3eadec16d1f 100644 --- a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md +++ b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md @@ -42,7 +42,7 @@ intro: The sections below include the coding conventions with respect to top-lev * Do not keep spaces between the organization name, divider `/`, and module name. - **Example,** + **Example:** ```ballerina import ballerina/http; @@ -54,7 +54,7 @@ intro: The sections below include the coding conventions with respect to top-lev * Use the SCREAMING_SNAKE_CASE for constant names. - **Example,** + **Example:** ```ballerina // don't @@ -68,7 +68,7 @@ intro: The sections below include the coding conventions with respect to top-lev * It is recommended to define the constants without the type descriptor, unless the type descriptor is used as the inherent type. - **Example,** + **Example:** ```ballerina // don't @@ -82,7 +82,7 @@ intro: The sections below include the coding conventions with respect to top-lev * Explicitly defining the type descriptor can enhance readability, particularly when the constant is defined with a compound expression. This practice provides clarity about the expected type. - **Example,** + **Example:** ```ballerina // don't @@ -97,7 +97,7 @@ intro: The sections below include the coding conventions with respect to top-lev ## Function definition * Do not keep spaces between the function name and the open parentheses `(` of the function signature. - **Example,** + **Example:** ```ballerina function func1() { @@ -106,7 +106,7 @@ intro: The sections below include the coding conventions with respect to top-lev * If the function needs to be split into new lines due to it exceeding the max line length, you can break lines from the parameter list by moving only a parameter value to a new line and indenting it with four spaces from the starting position of the function. - **Example,** + **Example:** ```ballerina function getAddress(int value, @@ -117,7 +117,7 @@ intro: The sections below include the coding conventions with respect to top-lev - You can break before the `returns` keyword and indent it with four spaces from the starting position of the function. - **Example,** + **Example:** ```ballerina function getAddress(int value, string name) @@ -129,7 +129,7 @@ intro: The sections below include the coding conventions with respect to top-lev - You can break after the `returns` keyword by moving the return value to a new line and indenting it with four spaces from the starting position of the function. - **Example,** + **Example:** ```ballerina function getAddress(int value, string name) returns @@ -142,7 +142,7 @@ intro: The sections below include the coding conventions with respect to top-lev * Keep the listener inline with the service signature. - **Example,** + **Example:** ```ballerina service / on new http:Listener(9090) { @@ -153,7 +153,7 @@ intro: The sections below include the coding conventions with respect to top-lev * When formatting service-level method definitions, block indent each element and follow the [Function definition](/learn/style-guide/top-level-definitions/#function-definition) formatting guidelines. - **Example,** + **Example:** ```ballerina import ballerina/http; @@ -175,7 +175,7 @@ intro: The sections below include the coding conventions with respect to top-lev * The `init` method should be placed before all the other methods. * For method definitions in the class definition, follow the [Function definition](/learn/style-guide/top-level-definitions/#function-definition) formatting guidelines. - **Example,** + **Example:** ```ballerina class Person { @@ -205,7 +205,7 @@ intro: The sections below include the coding conventions with respect to top-lev ## Record definition * Block indent each of the field definitions (including the rest field) in their own line. - **Example,** + **Example:** ```ballerina type Person record {| @@ -224,7 +224,7 @@ intro: The sections below include the coding conventions with respect to top-lev ## Reference record or object * Do not keep spaces between the `*` and the object name or the record name. - **Example,** + **Example:** ```ballerina *Person; From 0c2ed78d04d150c0bfda016e6ab47f21a4b80ef5 Mon Sep 17 00:00:00 2001 From: lochana-chathura <39232462+lochana-chathura@users.noreply.github.com> Date: Thu, 2 May 2024 13:03:25 +0530 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Maryam Ziyad --- .../style-guide/top-level-definitions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md index 3eadec16d1f..5766d16ad44 100644 --- a/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md +++ b/swan-lake/development-tutorials/source-code-dependencies/style-guide/top-level-definitions.md @@ -52,7 +52,7 @@ intro: The sections below include the coding conventions with respect to top-lev ## Constant declaration -* Use the SCREAMING_SNAKE_CASE for constant names. +* Use SCREAMING_SNAKE_CASE for constant names. **Example:** @@ -66,7 +66,7 @@ intro: The sections below include the coding conventions with respect to top-lev const MIN_AGE = 20; ``` -* It is recommended to define the constants without the type descriptor, unless the type descriptor is used as the inherent type. +* The type descriptor can be omitted in a constant declaration unless the type descriptor is required to construct the value (e.g., provide defaults, provide expected types to determine the inherent type, etc.). **Example:** @@ -80,7 +80,7 @@ intro: The sections below include the coding conventions with respect to top-lev const TAX_RATE = 0.15d; ``` -* Explicitly defining the type descriptor can enhance readability, particularly when the constant is defined with a compound expression. This practice provides clarity about the expected type. +* Explicitly defining the type descriptor can enhance readability, particularly when the constant is defined with a compound expression. **Example:**