Comments

Comments are used to provide more details about the code or temporally disable a section of the source code.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Hello world Ballerina Program.
import ballerina/io;

// My Main function.
public function main() {
    io:println("Hello World...!!!"); // printing hello world.

    // io:println("No execution.");
}

// End of this example.

Hello World...!!!

Ballerina 2201.6.0 (Swan Lake Update 6)

Code Explained

• Line 1: This is a comment. It provides more details about the code.
• Line 4: This is another comment, but do not use comments to document functions; Instead, use markdown documentation syntax.
• Line 6: This is an inline comment, but the code is self-explanatory. Avoid such comments.
• Line 8: This is commented out code. It is used to temporarily disable a section of the source code.
• Line 11: This comment is unnecessary and should be avoided in favor of clear, concise code.

Multi-line comments are useful when providing large text descriptions or commenting on multiple lines of the code. Many languages use /* */ syntax for multiline comments. Ballerina does not support this syntax. Instead, you can use multiple // comments for the same purpose.

IDEs such as VSCode provide better support when commenting out multi-line code blocks. Select lines you want to comment on, then press Ctrl + / key.

It is common to keep documentation within the source code because it is easy to keep up-to-date documentation with the code changes. In many programming languages, Documentation is kept as comments & sometimes formatted in a particular way (e.g.: /** */ syntax in Java).

In Ballerina, you can use markdown documentation syntax to document Ballerina constructs. Ballerina markdown documentation starts with #. It is a common mistake that the developer uses comments (//) for documentation purposes.

Some programming languages often use comments to store metadata about the program. In Ballerina, you can use annotation for this purpose. But usually, you don’t need to define annotations, unless you are building a low-level connector or extending compiler functionalities. If you are not sure whether you need to use annotation, you probably don’t need it, get help from the Ballerina Team and Community.

Rarely, you write perfect code and run forever. Coding is an iterative process; You need to add new features, improve your code, and fix bugs. So, you must continue reading your old code to know how/where to fix it.

So, write your code in a self-documenting or understandable way. Put comments if necessary. Do not make updating comments in sync with the source code is an excessive task.

Below are the main points to remember:

• No Multiline Comments.
• Only for Comments.
• Do not document inside comments, use Markdown syntax instead.
• Avoid comments much as possible, use clear, concise code instead.