Code Examples Best Practices

In this tutorial, you will learn about Code Examples Best Practices. We cover key concepts, practical examples, and best practices to help you master this topic.

Code examples are the most valuable part of API documentation. Learn to write clear, tested, consistent code examples across multiple languages that developers can copy, paste, and run successfully on their first try every single time.

What You'll Learn

How to write code examples that work on first copy-paste, how to keep examples consistent across languages, how to handle authentication in examples, how to test examples automatically, and how to format examples for maximum readability.

Why It Matters

Developers scan API documentation for code examples first. A working example that they can copy, paste their API key, and run is the fastest path from evaluation to integration. A broken example destroys trust instantly and permanently.

Real-World Use

The DodaTech documentation team tests every code example against the actual API before publishing. They run examples in CI to catch breakage when the API or SDK changes. This ensures every example in the documentation works on the first copy-paste.

Code Example Structure

flowchart TD
  A[Code Example] --> B[Complete Setup]
  A --> C[Clear Variables]
  A --> D[Error Handling]
  A --> E[Expected Output]
  B --> F[Include imports]
  B --> G[Show initialization]
  C --> H[Useful variable names]
  D --> I[Basic try-catch]
  E --> J[Show what to expect]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Complete Runnable Examples

Every code example must be complete. Include imports, initialization, and all necessary setup.

# GOOD: Complete example with imports and initialization
import os
from dodatech import Client

client = Client(api_key=os.environ["DODATECH_API_KEY"])
files = client.files.list(per_page=5)

for file in files:
    print(f"{file.name}: {file.size_bytes} bytes")

# BAD: Missing imports and setup
files = client.files.list()
print(files)

Environment Variables for Secrets

Never hardcode API keys. Use environment variables and clear placeholders.

import os

# Always use environment variables for secrets
client = Client(api_key=os.environ["DODATECH_API_KEY"])

# Never hardcode: client = Client(api_key="sk_live_abc123")

// Use environment variables
const client = new Client({
  apiKey: process.env.DODATECH_API_KEY,
});

# Set environment variable before running
export DODATECH_API_KEY="your-api-key-here"

Expected Output

Show the expected output after every code example.

import os
from dodatech import Client

client = Client(api_key=os.environ["DODATECH_API_KEY"])
files = client.files.list(per_page=3)

for file in files:
    print(f"{file.name}: {file.size_bytes} bytes")

# Expected output:
# report.pdf: 1048576 bytes
# data.csv: 256000 bytes
# image.png: 5242880 bytes

Consistent Examples Across Languages

When showing examples in multiple languages, use the same variable names and request data.

# Python
result = client.files.compress(
    file_url="https://example.com/document.pdf",
    format="zip",
    level=6
)
print(result.job_id)

// JavaScript
const result = await client.files.compress({
  fileUrl: "https://example.com/document.pdf",
  format: "zip",
  level: 6,
});
console.log(result.jobId);

# cURL
curl -X POST https://api.dodatech.com/v2/files/compress \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://example.com/document.pdf", "format": "zip", "level": 6}'

Handling Errors in Examples

Show basic error handling so developers learn good practices from the start.

import os
from dodatech import Client, AuthenticationError, RateLimitError

client = Client(api_key=os.environ["DODATECH_API_KEY"])

try:
    files = client.files.list()
    print(f"Found {len(files)} files")
except AuthenticationError:
    print("Invalid API key. Check your credentials.")
except RateLimitError as e:
    print(f"Rate limited. Retry in {e.retry_after} seconds.")
except Exception as e:
    print(f"Unexpected error: {e}")

Common Mistakes

1. Untested Examples

Publishing code examples that have not been tested against the actual API. Always test every example before publishing.

2. Hardcoded Secrets

Including real or realistic-looking API keys in examples. Always use placeholder values and environment variables.

3. No Imports or Setup

Showing only the core API call without imports, client initialization, or environment setup. Developers cannot run the example as-is.

4. No Expected Output

Showing code without what the output should look like. Developers cannot verify their code worked correctly.

5. Inconsistent Naming

Using camelCase in one language and snake_case in another for the same concept. Keep naming consistent across examples.

6. No Error Handling

Showing only the happy path without any error handling. Developers copy this pattern and miss critical error handling.

7. Overly Complex Examples

Showing advanced features and edge cases in what should be a simple example. Keep examples focused on one task.

Practice Questions

1. What makes a code example complete and runnable?

Includes all imports, client initialization with environment variables, the core API call, print statements showing output, basic error handling, and expected output as comments.

2. Why use environment variables for API keys in examples?

Environment variables keep credentials out of source code, prevent accidental commits, and teach developers a security best practice from the start.

3. How do you keep examples consistent across multiple languages?

Use the same variable names, request data values, and expected output structure across all language examples. Adapt to language conventions (camelCase in JavaScript, snake_case in Python).

4. Why show expected output after code examples?

Expected output lets developers verify their code worked correctly. Without it, they cannot distinguish between a successful run and one that silently failed.

5. Challenge: Write the same API operation as code examples in cURL, Python, and JavaScript. All three examples must use consistent data, include environment variables for secrets, handle errors, and show expected output.

FAQ

Mini Project: Code Example Testing

Write code examples for an API endpoint in cURL, Python, and JavaScript. Ensure all three use consistent data and produce the same output. Test every example against the real API. Write a test script that verifies all examples work and can be run in CI.

What's Next

Master code examples in raw HTTP and SDK forms with From cURL to SDK Examples. Then explore Organizing Endpoints for structuring API documentation.