Glossary · 1 · SDK fundamentals

Code sample

Also known as: Sample code, Code example, Example code

German: Codebeispiel

In software engineering, a code sample is a short, self-contained piece of example code in documentation that shows how to accomplish one task with a library, API, or toolchain. It is written to be read and run, so it normally compiles or executes as given, uses the same language and version as the product it documents, and is shipped and revised together with that product. Style guides for developer documentation treat code samples as a content type in their own right, with rules for formatting, completeness, and testing, next to reference documentation.

SDK
documentation
code examples
developer experience
technical writing

In one sentence

What a code sample is in SDK documentation: a short, runnable example for one task, kept complete, tested, and versioned with the product.

Example

For the storage SDK, the writing team publishes a 20-line Python code sample that uploads one file, tests it in continuous integration on every release, and links it from the method reference.

How it applies

One task, one sample. A code sample answers a single question ("how do I upload a file?", "how do I subscribe to an event?"). Scenarios that need several steps belong in a tutorial or a full sample application, not in one block.
Complete and runnable. Readers copy samples. Imports, client construction, error handling, and cleanup should be present or explicitly pointed to; omissions are marked with a comment in the language of the sample rather than an ellipsis, and blocks with omissions should not be offered as click-to-copy code.
Tested, not just written. Samples that live in the repository of the software development kit and are compiled or executed in continuous integration stay correct; untested snippets pasted into prose tend to drift out of date as the product changes.
Versioned with the product. Tie each sample to a release line and state the version it was verified against, ideally following semantic versioning, so readers of an older branch see code that still works for them.
Developer SDKs (APIs and cloud services). Samples cover client setup, authentication with a credential, pagination, retries, and error cases for an application programming interface or REST API. They are commonly generated per language from an interface definition and then curated by hand; see automatic code generation. Use placeholder values instead of real keys, and never present a sample as evidence that an integration is secure or compliant.
Publishing SDKs (structured content, multichannel output). In DITA, examples are marked up with the <codeblock> element of the programming domain (with <coderef> to pull in an external file) and framed by <example>; reuse via conref and conditional processing lets one tested sample appear in several deliverables and output channels. Keep whitespace handling and line length in mind, since PDF and help output wrap differently.
Platform SDKs (extending host applications). Samples usually need a host context — a manifest, an extension point, a lifecycle callback — so state the host application version and the minimum API level the sample assumes.
Hardware SDKs (devices, processors, accelerators, XR). Samples depend on a board, driver, or accelerator, so they document build flags, toolchain version, and target hardware, and often ship as sample projects that run in simulation when the device is absent. For embedded software and firmware, note which peripherals and clock settings the example expects.
Editorial hygiene. Follow the language's own style guide for indentation and naming, wrap long lines, mark blocks as preformatted, use realistic but non-production data, and state the license under which the sample may be reused.
Findability. Cross-link samples from reference entries and from the JSON payloads or schemas they illustrate, and keep a single canonical copy to avoid divergent variants across the docs set.

Code sample vs. code snippet

A snippet is a fragment — a few lines lifted from a larger program to illustrate one call or parameter; it is real code but not independently runnable. A code sample is a self-contained unit that a reader can run as given, with the surrounding setup needed to execute. Snippet-heavy documentation is cheaper to write but degrades faster, because fragments are rarely covered by tests; sample programs can be built and executed on every change. Both differ from a sample application, which demonstrates architecture across many tasks and is maintained as its own project. Neither is a substitute for reference documentation: samples show usage, reference documentation enumerates the programming elements. When a sample does not behave as described, treat it as a debugging input, not as a specification of the interface.

In one sentence

Example

How it applies

Code sample vs. code snippet

External references