Code Sample Standard Template

Code Sample Standard: [Documentation set or product name]

Rules for code samples and snippets in documentation: what a sample must contain, how it is tested in CI, how it is licensed and attributed, how it handles secrets, versions and errors, and how it is reviewed and retired. Licence tagging follows SPDX identifiers and the REUSE Specification 3.3. Replace every [bracketed] value and every row marked Example. The examples use a fictional SDK, the Quarrow Storage SDK.

Document control

Revision history

1. Sample types

2. Content rules

1. Show the task, not the API. Each sample solves one task named in its heading ("Upload a file with a retry"), not "Using putObject".
2. Complete enough to run. Complete samples include imports, client setup and cleanup. Snippets state what they assume in a comment.
3. Handle errors as production code would. Catch the documented errors and show what to do; never swallow exceptions silently.
4. Use realistic, harmless values. Use reserved example domains (example.com), placeholder IDs and the fictional names from your style guide.
5. Pin versions. State the SDK or runtime version the sample was tested with.
6. Show the output. Give expected output after commands and samples, so readers can tell whether they succeeded.
7. Follow the language's idioms and formatter. Run the standard formatter and linter for the language.
8. Keep it short. Remove everything that does not serve the task. Move setup code into a shared helper if it repeats.
9. Comment the why. Comments explain decisions and caveats, not what each line does.

Example complete sample (Python):

# SPDX-FileCopyrightText: 2026 Quarrow Labs
# SPDX-License-Identifier: MIT-0
# Tested with quarrow-storage 2.3.1 and Python 3.13.
import os

from quarrow_storage import Client, NotFoundError

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

try:
    obj = client.objects.get(bucket="reports", key="2026/q3.pdf")
    print(f"Downloaded {obj.size} bytes")
except NotFoundError:
    print("No report for Q3 yet. Check the key or upload it first.")

3. Secrets and security

• Never put real credentials, tokens or private URLs in a sample. Read secrets from environment variables or a secret store and say so.
• Use placeholder values that secret scanners recognise as fake, and run a secret scanner on the docs repository.
• Do not disable TLS verification, use deprecated cryptography or turn off input validation in a sample, even "for simplicity".
• Apply least privilege in examples of permissions and policies.
• Security review is required for samples about authentication, cryptography, payments and access control.

4. Testing

Rules:

• Tests run on every docs change and on every SDK release, so a breaking SDK change fails the docs build.
• A sample that cannot be tested (for example, it needs real hardware) is labelled "Not tested in CI" with the date it was last checked by hand, and reviewed every [6] months.

5. Licensing and attribution

• Publish samples under a permissive licence that does not require attribution in the reader's code, such as MIT-0 or 0BSD, or state clearly what the licence requires. (Decision: [licence])
• Tag each sample file with SPDX-FileCopyrightText and SPDX-License-Identifier headers, and keep the licence texts in a LICENSES/ directory, as the REUSE Specification 3.3 describes. Where per-file headers are impractical, use a REUSE.toml file.
• If the docs text has a different licence from the code (for example CC BY 4.0 for prose), say so in the site footer.
• Do not paste third-party code into samples unless its licence allows it, and keep its original copyright notice and identifier.
• Do not publish code generated by an AI assistant without the same review, testing and licence check as human-written code.

6. Presentation

• Always set the language on fenced code blocks for highlighting.
• Show prompts ($) only in shell samples where output is shown, and make the copy button strip them.
• Use tabs for the same sample in several languages; keep the variable names and steps identical across tabs.
• Mark lines the reader must change with a comment such as # Replace with your bucket name.
• Keep line length under [80] characters so samples do not scroll on narrow screens.

7. Versioning and retirement

8. Review checklist

• Solves one named task and runs as published (or compiles in harness).
• Tested in CI, with the tested version stated.
• No secrets, no insecure shortcuts, errors handled.
• SPDX header present and licence matches the decision in section 5.
• Formatter and linter pass; idiomatic for the language.
• Expected output shown; lines to change are marked.

9. Ownership and metrics

10. References

• SPDX License List, version 3.29.0 (2026-09-16): https://spdx.org/licenses/.
• REUSE Specification, version 3.3 (2024-11-14): https://reuse.software/spec-3.3/.
• Related templates: docs/docs-contribution-guide, docs/style-guide-technical, docs/sdk-overview, docs/developer-guide, dev/coding-standards, dev/library-readme.

Standard and licence note

Based on common docs-as-code practice and on the public SPDX License List and REUSE Specification 3.3 for licence tagging. This template is original text written for this collection. Check the current SPDX list and REUSE version before relying on them, and ask your legal or open source office to confirm the sample licence. Template licence: MIT.