Code Example Types

Note

Although "code example" and "snippet" are often used interchangeably, this guidance uses "snippet" specifically to refer to a context-less block of code. See Snippets for more information.

We categorize code examples into the following types:

Usage Examples: Standalone code blocks that show how to perform a task, including the relevant setup and context.
Snippets: Code that illustrates a specific concept or detail within the context of a larger example, tutorial, or reference page.
Sample Applications: Runnable applications demonstrating broader use cases.

Usage Examples

Usage examples are self-contained, actionable code blocks that show how to accomplish a specific task using MongoDB tools, drivers, or APIs.

Usage examples include enough information to understand, modify, and run the code contained in the code block. For example, a single code block that contains declared variables, comments, descriptive placeholders, and other information necessary to run the code:

using MongoDB.Driver;
// Replace the following with your MongoDB connection string
const string connectionUri = "mongodb://<db_username>:<db_password>@<hostname>:<port>/?connectTimeoutMS=10000";
var client = new MongoClient(connectionUri);

Snippets

Snippets are narrowly scoped code blocks that help explain a specific concept or detail. Snippets are typically used as part of a broader explanation or tutorial, and are often meaningful only within that context.

Snippets are intended to provide information. They are not required to be valid or runnable code. In some cases, snippets may contain intentionally incomplete or incorrect code for demonstration purposes (for example, a snippet showing all possible arguments for a command).

Snippets can be one of the following subtypes:

Non-MongoDB Command

A command-line (CLI) command for any non-MongoDB tooling (for example, mkdir, cd, or npm), commonly used in the context of a tutorial.

These are most often used alongside usage examples as an intermediary step to complete a task.

Non-MongoDB command

dotnet run MyCompany.RAG.csproj

Syntax Example

An example of the syntax or structure for an API method, an Atlas CLI command, a mongosh command, or other MongoDB tooling. These are commonly used in reference pages or sections.

Unlike usage examples, syntax examples are intended for demonstration purposes and are not intended to be executed as written. For example, a snippet showing all possible arguments for a command would be intentionally non-executable code:

Syntax example

db.collection.createIndex(
{
   <field>: <sortOrder>
},
{
   collation:
      {
         locale : <locale>,
         strength : < 1 | 2 >
      }
   }
)

Note

Syntax examples often include placeholders that users should replace with actual values. For more information on placeholders, see Code Example Guidelines.

Example Return Object

An example of an object, such as a JSON blob or sample document, returned after executing a corresponding piece of code.

Example return objects are commonly included as the output of an io-code-block. To learn how to use an io-code-block, see the Code Examples reference.

Example return object

 A timeout occurred after 30000ms selecting a server.
 Client view of cluster state is
 {
     ClusterId : "1",
     State : "Disconnected",
     Servers :
     [{
       ServerId: "{ ClusterId : 1, EndPoint : "localhost:27017" }",
       EndPoint: "localhost:27017",
       State: "Disconnected"
     }]
 }

Note

Example return objects are usually not meant to be copied and executed. To learn how to make a code block non-copyable, see Code Example Formatting.

Configuration Object

An example of a configuration object, often represented in YAML or JSON, that enumerates parameters and their types. These can be part of a larger tutorial or provided as a reference. For example, a config object that demonstrates a Terraform or Atlas CLI configuration settings:

Example configuration object

 apiVersion: atlas.mongodb.com/v1
 kind: AtlasDeployment
 metadata:
 name: my-atlas-cluster
 spec:
 backupRef:
     name: atlas-default-backupschedule
     namespace: mongodb-atlas-system

Note

Use your best judgment to determine whether a configuration object is meant to be copied and executed. To learn how to make a code block non-copyable, see Code Example Formatting.

Sample Applications

Sample applications are complete, runnable programs that connect multiple discrete pieces of code. Sample apps might include error handling, framework integrations, or frontend UI elements. These are often provided as a companion to a tutorial or guide, sometimes in a dedicated repository.

Sample apps are intended to be copied, modified, and executed by users, and can demonstrate a more complex use case than a usage example.

See the Docs Sample Apps GitHub repo for a collection of sample applications.

Back

Code Examples

Code Example Guidelines