Sample Code Projects — Building Complete Examples for Developer Documentation

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

Sample code projects are complete, runnable applications that demonstrate how to use a library or API in a real-world context. Unlike code snippets, sample projects include all the surrounding infrastructure needed for a working application.

In this lesson, you will learn how to create sample code projects that developers can clone, run, and learn from.

What You'll Learn

You will structure sample code projects, write README files for them, and create real-world scenarios that demonstrate library usage.

Why It Matters

Sample code projects reduce the time from discovery to first working integration. Developers prefer cloning a complete project over assembling snippets.

Real-World Use

DodaTech ships sample projects for each DodaZIP feature. The log compression sample project is the most cloned Repository, reducing integration time from hours to minutes.

flowchart LR
  A[Sample Project] --> B[README]
  A --> C[Complete Code]
  A --> D[Tests]
  A --> E[Setup Scripts]
  B --> F[Developer Clones]
  C --> G[Runs Immediately]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Sample Project Structure

Every sample project should include a README that explains what it demonstrates, prerequisites, setup instructions, and expected output.

Include a requirements file or dependency manifest. Developers should install dependencies with one command.

Include tests that verify the sample works. Developers trust tested examples.

Include a setup script that prepares any needed data or configuration.

# Sample project structure

log-compressor/
  README.md
  requirements.txt
  setup.sh
  compress_logs.py
  tests/
    test_compress_logs.py
  sample_data/
    server-1.log
    server-2.log

Writing the README

The README should answer four questions in order: What does this sample demonstrate? What do I need before starting? How do I run it? What should I see?

Keep setup instructions minimal. One or two commands to get running.

Show the expected output after running. Developers verify they succeeded.

# Log Compressor Sample

This sample demonstrates how to compress log files using DodaZIP
streaming compression with scheduled execution via cron.

## Prerequisites

- Python 3.9 or later
- DodaZIP 2.1 or later

## Setup

```bash
pip install -r requirements.txt
bash setup.sh

Run

python compress_logs.py --directory sample_data --output compressed

Expected Output

Compressed server-1.log: 12400 -> 3200 bytes (25.8%) Compressed server-2.log: 12400 -> 3150 bytes (25.4%) Total: 24800 -> 6350 bytes (25.6%)

Common Mistakes

1. No README

A sample project without instructions. Developers cannot tell what it does or how to run it.

2. Missing Dependencies

requirements.txt or package.json missing. Developers cannot install what is needed.

3. Hardcoded Paths

Sample code with hardcoded paths that only work on the author's machine.

4. No Sample Data

Code that reads from files but no sample data included.

5. No Tests

Sample code without tests. Developers cannot verify it works after modifying.

6. Too Complex

Sample project that demonstrates too many features. Keep each sample focused.

7. Outdated Code

Sample projects that use deprecated APIs. Update with every release.

Practice Questions

1. What should every sample project include?

A README, dependency manifest, complete code, sample data, tests, and setup scripts.

2. What are the four questions the README should answer?

What does it demonstrate? What do I need? How do I run it? What should I see?

3. Why include sample data with the project?

Developers can run the sample immediately without preparing their own data.

4. Why should sample projects include tests?

Tests verify the sample works and continue working after modifications.

5. Challenge: Create a sample project structure for a tool you use. Write the README, create the file structure, and write one complete sample script with tests.

FAQ

Mini Project

Create a sample project for a feature of DodaZIP or another tool you know. Include a README, dependency file, complete code, sample data, tests, and setup script.

What's Next

Next: Developer Tutorials