# Explain code samples for readers who cannot rely on highlighting

Canonical: https://githtml.com/guides/explain-code-for-nonvisual-reading
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

Introduce what a code sample does, identify its inputs and placeholders, and explain the lines that matter in ordinary prose. Keep the source selectable and correctly escaped. Syntax highlighting can assist visual scanning, but the sample's meaning and safety conditions should not depend on color, indentation alone, or a screenshot.

## Provide a reading contract

Before a sample, state whether it is a complete file, a fragment, or pseudocode. Name the language and the context in which it belongs. A reader hearing punctuation through assistive technology benefits from knowing the example's purpose before encountering its details. The same introduction helps a mobile reader deciding whether to inspect the code closely.

Identify placeholders explicitly. A string that looks like a real hostname or token can be mistaken for a usable value. Explain which values must change and which should remain exactly as shown. Put prerequisites and warnings before the sample, particularly when a command writes files or changes state. Do not leave operational caveats only in code comments.

## Explain structure outside the sample

Describe the important behavior in a short paragraph or list. For a configuration example, explain what each relevant setting controls and how the settings interact. For a function, explain the input, output, and failure condition. Avoid mechanically narrating every punctuation mark; the goal is conceptual understanding, not duplicating the entire source in awkward prose.

If indentation carries meaning, preserve it in selectable text and explain the hierarchy where necessary. If syntax colors distinguish added and removed lines, add explicit labels or a separate change summary. A red line and a green line should not be the only evidence of what changed. Screenshots of code are especially weak because they restrict selection and can become unreadable on a phone.

## Check multiple reading paths

Review the sample without highlighting and listen to a representative portion with assistive technology when possible. Copy the rendered code into a plain-text editor to confirm that formatting did not introduce misleading characters. A code element supplies semantics but does not automatically escape literal HTML tags; the export must handle that boundary correctly.

1. State the sample's purpose and whether it is executable.
2. Name the language and required context.
3. Explain placeholders before the code.
4. Summarize the important behavior in prose.
5. Check that meaning survives the removal of syntax colors.
6. Verify copied text and preserve essential indentation.
7. Keep secrets and real credentials out of all examples.

## Sources and further reading

- [MDN: code element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/code)
- [W3C: understanding use of color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html)

## Related guides

- [Build a heading outline that makes a long report navigable](https://githtml.com/guides/heading-hierarchy-readable-html)
- [Use landmarks to separate navigation from the report body](https://githtml.com/guides/document-landmarks-for-html-reading)
- [Write screenshot alternatives that explain the useful information](https://githtml.com/guides/alt-text-for-document-screenshots)
- [Describe architecture diagrams as relationships, not shapes](https://githtml.com/guides/text-descriptions-for-architecture-diagrams)

Editorial approach: https://githtml.com/guides/about