The sections below include the coding conventions with respect to annotations, documentation, and comments.
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,
// Parameter annotation. public function secureFunction1(@untainted string secureInName, @untainted int secureInId, string insecureIn) { ... } public function secureFunction2(@untainted string secureInName, @untainted int secureInId, string insecureIn) { ... } // Return type annotation. public function taintedReturn1() returns @tainted string { ... } public function taintedReturn2() returns @tainted string { ... }
Comments
- Use
//
for both single-line and multi-line comments.
Example,
// This is a single-line comment.
and
// Copyright (c) 2022 WSO2 LLC (http://www.wso2.org) All Rights Reserved. // // WSO2 LLC licenses this file to you under the Apache License, // Version 2.0 (the "License"); you may not use this file except // in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, // software distributed under the License is distributed on an // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY // KIND, either express or implied. See the License for the // specific language governing permissions and limitations // under the License.
- 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 (true) { if (true) { // 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 (-
), andreturn
. - 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) { ... } }
"Star"
"Watch"