Skip to content

Ballerina By Example guidelines

Jump to bottom
praneesha edited this page Jan 10, 2023 · 34 revisions

Below is a list of guidelines that must be followed when updating and adding new BBEs and API Docs.

General guidelines

  1. Make the BBEs small, simple, and straightforward. Do not create examples with large lines of code. Otherwise, it will require scrolling through a large example to understand the use case.

  2. Create realistic examples whenever possible. Make sure the example, which explains some features shows a practical scenario when it can be used. However, sometimes, it may not be possible to create a small-enough practical scenario. It will be required to use your judgment to decide that.

  3. After creating/updating BBEs, generate the HTML files and deploy them on the website to verify if everything is displayed correctly.

Creation-related guidelines

Info: For instructions on creating BBEs, see Create Ballerina By Examples.

  1. Each new BBE should have its own directory named after it. The directory name should be in all lowercase letters. Use hyphens (-) in the directory names (e.g., hello-world) and underscores (_) in the file names (e.g., hello_world.bal).

  2. If a new example is added/deleted, update the index.json file as well.

    Info: Individual BBEs can be configured to disable the playground link generation and to override the default GitHub edit URL by setting the disablePlayground and githubLink properties accordignly in the index.json file.

    For example,

    {
	"title": "Ballerina Basics",
	"column": 0,
	"category": "Language concepts",
	"samples": [
    	{
        	"name": "Functions",
        	"url": "functions",
        	"githubLink": "https://github.com/ballerina-platform/ballerina-lang/tree/ballerina-1.2.x/examples/functions/",
        	"disablePlayground": true
    	}
	]
}

  3. Service examples demonstrating client-server scenarios have a .bal file only for the server and two different output files. That is, one to display the server output (.server.out file) and the other (.client.out file) to display the cURL command and the output. These two separate output files can be introduced with .server and .client suffixed to the file names.

    Info: For example, see the hello_world_service.server.out and hello_world_service.client.out files below of the Hello world service BBE.

  4. Unless it is really required, it is not encouraged to have multiple BAL files in the same sample. In that case, each BAL file can have its own name and the .out file should match the name of the .bal file. For example,

    A service example

Ballerina code related guidelines

  1. Use language features to make the examples look elegant (and small). For example, string templates, functional iteration, anonymous functions, etc.

  2. Use meaningful variable names, function names, etc.

  3. Remove unused imports in .bal files.

  4. Format the Ballerina source using an IDE Plugin.

  5. Do not set (too many or any) optional properties (e.g., JDBC connection pooling props). Users will figure it out with code assistance or with additional documentation as those will be covered in Learn guides. Also, all the possible options will be covered in the API docs.

  6. Simplify error handling. Use check whenever possible. These examples do not need to show all possible error-handling situations. These possibilities can be shown in the actual error-handling BBEs.

  7. As a practice, use ballerina/io methods in main examples and ballerina/log methods in the examples with services. Do not use both io:println and log:printInfo in the same sample.

  8. Add comments in the BAL files as much as possible with “//” as they are used as a mechanism to describe the code.

  9. The comments should be valid sentences (i.e. start with an upper case letter and end with a full stop etc.), and try to keep the code-level comments short.

Content-related guidelines

  1. Write BBE content in general markdown syntax in the MD file.

  2. All titles should be in sentence case (i.e., only the first letter of the title should be in uppercase).

  3. All keywords and any other word, which needs to be highlighted should be used with backquotes (e.g., xml). Do not use a single quote as it will not get highlighted on the Ballerina website.

  4. The files will be displayed on the website in the order in which you include them in the markdown file.

  5. Empty lines will be ignored when content is rendered and new lines will be rendered with the spacing specified for them.

  6. The BBE generation script reads and converts the content of the Markdown file line by line. However, in the case of a Markdown code block spanned across multiple lines, it reads it as a whole. Also, it ignores any empty lines in the Markdown file.

  7. To add a new line in the rendered BBE content, adding a new line in the usual Markdown format will be sufficient. If a line exceeds the character limit of the BBEs body section, the remaining text of the line will be shifted to a new line with the spacing of text in a paragraph.

Output-related guidelines

As a best practice, add the bal command and the corresponding output by truncating it as a common pattern in the .out files. For example,

$ bal grpc --input grpc_bidirectional_streaming.proto  --output stubs
Successfully extracted the library files.
Successfully generated the Ballerina file.
Clone this wiki locally