Code Examples Best Practices — Writing Runnable, Clear, and Teachable Code

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 important element of developer documentation. A good code example teaches more than paragraphs of explanation. A bad code example destroys trust and wastes time.

In this lesson, you will learn how to write code examples that developers can run, understand, and adapt.

What You'll Learn

You will write runnable code examples, show expected output, use progressive disclosure, and include real-world context.

Why It Matters

Developers learn by reading and running code. Every code example is a teaching opportunity.

Real-World Use

DodaTech rewrote all DodaZIP code examples to be runnable with expected output. The time to first successful compression dropped from 15 minutes to 90 seconds.

flowchart LR
  A[Code Example] --> B[Runnable]
  A --> C[Shows Output]
  A --> D[Teaches Concept]
  A --> E[Real Context]
  B --> F[Copy and Run]
  C --> G[Verify Results]
  D --> H[Learn Pattern]
  E --> I[Apply to Work]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Runnable Examples

Every code example must work when copied and pasted. Include all imports, variable definitions, and necessary setup.

Show the minimal code needed to demonstrate the concept. Remove distractions but keep the example complete.

Test every code example before publishing. Run it in a clean environment to verify it works.

# Runnable example: complete and minimal

# Import the library
from dodazip import Compressor

# Create a compressor with gzip algorithm
c = Compressor(algorithm="gzip", level=6)

# Compress a file
result = c.compress_file("data.csv")

# Display results
print(f"Original: {result.input_size} bytes")
print(f"Compressed: {result.output_size} bytes")
print(f"Ratio: {result.ratio:.1%}")

# Expected output:
# Original: 1048576 bytes
# Compressed: 258432 bytes
# Ratio: 24.6%

Progressive Disclosure

Start with a simple example that demonstrates the basic concept. Add complexity in subsequent examples.

Each example builds on the previous one. Readers can stop when they have learned enough.

Show the problem first, then the solution. Developers understand why the solution matters when they see the problem.

# Step 1: Basic compression
from dodazip import Compressor
c = Compressor()
result = c.compress_file("data.csv")
print(f"Compressed: {result.output_size} bytes")

# Step 2: With error handling
try:
    result = c.compress_file("missing.csv")
except FileNotFoundError:
    print("File not found, using empty data")

# Step 3: Batch processing multiple files
files = ["data1.csv", "data2.csv", "data3.csv"]
for file in files:
    result = c.compress_file(file)
    print(f"{file}: {result.ratio:.1%} ratio")

Common Mistakes

1. Missing Imports

Code snippets without import statements. Readers must guess what to import.

2. No Expected Output

Showing code but not what the reader should see when they run it.

3. Overly Complex Examples

One example trying to demonstrate too many concepts. Keep each example focused.

4. Not Testing

Code examples with typos or logic errors. Test every example from scratch.

5. No Real-World Context

Examples that demonstrate syntax but not real usage. Show how the code applies to actual problems.

6. Too Long

Code blocks over 20 lines that readers skip. Break long examples into smaller blocks.

7. No Error Handling

Showing only the happy path. Developers need to see how errors are handled.

Practice Questions

1. What makes a code example runnable?

Complete code with all imports and definitions. It works when copied and pasted.

2. What is progressive disclosure?

Starting with a simple example and adding complexity. Each step builds on the previous one.

3. Why show expected output?

Developers need to verify their results. Expected output confirms they are on the right track.

4. Why include error handling in examples?

Real-world code needs error handling. Developers learn how to handle failures by seeing examples.

5. Challenge: Take a complex API feature and write three code examples using progressive disclosure. Example 1: basic usage. Example 2: with error handling. Example 3: real-world batch processing.

FAQ

Mini Project

Take an existing code example from documentation you use. Identify three ways it could be improved: completeness, expected output, or progressive disclosure. Rewrite it applying all best practices from this lesson.

What's Next

Next: Explain Concepts Clearly