Code Examples

Add code examples where possible to show users how to work with Couchbase products.

When adding a code example:

Do

Make it relevant and applicable to your explanation.
Make sure it is a working code sample that the user could use in their own projects.
Put the code example in its own separate file.
Use the correct format for Code Placeholders.

Don’t

Include cultural references.
Write the code sample directly inside the .adoc file.

Introducing Examples

Use the following guidelines for adding an example into your documentation:

Don’t use directional language to describe where in the text your example is, like "above" or "below." Use "preceding," "previous," or "following."
Similar to links, use "see."
Use a colon at the end of the phrase you use to introduce your example.

Acceptable Not Acceptable

Acceptable	Not Acceptable
See the following example:	See the example below.
For an example of how to use a `SELECT` query, see the following: The following example shows how to use a `SELECT` query:	The example below shows how to use a `SELECT` query.

See the following example:

See the example below.

For an example of how to use a SELECT query, see the following:

The following example shows how to use a SELECT query:

The example below shows how to use a SELECT query.

Adding a Code Example

Antora supports two different methods of inserting smaller blocks of code into a page:

Add tags inside code comments to mark the code to include.
Choose specific line numbers to include.

Tags

To start a code sample, in the source code file, add tag::<TAG_NAME>[] in a code comment before the lines of code you want to include.

To end a code sample, in the source code file, add end::<TAG_NAME>[] in a code comment following the lines of code you want to include.

For example, the following code has two tags, using and connect:

using System;
// #tag::using[]
using System.Threading.Tasks;
using Couchbase;
// #end::using[]

namespace examples
{
    class StartUsing
    {
        static async Task Main(string[] args)
        {

            // #tag::connect[]
             var cluster = await Cluster.ConnectAsync("couchbase://localhost", "username", "password");
            // #end::connect[]

        ...
        }
    }
}

Line Numbers

To include a specific set of lines of code in your code, use the lines attribute inside your include directive.

For example, the following code would include lines 1-3 of the code file select-true-alias-get-business-days.n1ql:

include::example$javascript-udfs/select-true-alias-get-business-days.n1ql[lines=1..3]

For more information about how to include specific lines of content, see Include Content by Line Ranges in the Asciidoctor Documentation.

Explaining Code Examples

Avoid the built-in code callouts in Antora, where possible.

Use small code examples with the explanation in regular text around the example. Add one-line code comments directly to the code where appropriate to explain the assumptions made in a code example.

Let the user know they should remove the comments to use the code in a production environment.

When you need to explain a larger code example:

Show the full example and provide a brief explanation.
Create a smaller code example out of the larger block of code.
Provide a more detailed explanation for the smaller code example.
Repeat Steps 2 and 3 until you’ve explained the code.