Writing guide on header files is a supplement to the writing guide specifically for articles about C and C++ header files.

The goal of a header article is not to replicate documentation. cppreference and the POSIX manual pages already do that exhaustively. An article here should give a programmer a genuine understanding of the header: why it exists, how it feels to use it, what it gets wrong, and how the key parts are implemented under the hood.

Every header article must follow this structure, in this order:

# <header.h>
[Short description paragraph in wiki tone]

## Motivation
## Usage
## Examples
### <Example name>
### <Example name>
## Implementation
### <function or object name>
### <function or object name>
[Optional miscellaneous sections]
## Links

The title is the header name in angle brackets: # <string.h>. The first paragraph names the header in bold (e.g. <string.h>) and gives a one- or two-sentence description of what the header provides. This is the “what is it” answer.

The ## Motivation section illustrates why a programmer would include this header — what problem it solves, what becomes easier with it. This is not a function list. It is a narrative that shows the before and after, or a compelling example that makes the header feel necessary. For example, the motivation for <string.h> is strlen() and friends: without them, every program would reimplement string operations from scratch.

A good Motivation section answers: “What would I have to write myself if this header didn't exist, and why is that worse?”

The ## Usage section contains a single complete code example that illustrates the most common or most interesting artifact from the header. The example must:

• Be a complete, self-contained program with a main() function
• Have compile and run instructions in a comment block at the top
• Show something genuinely useful, not a toy “hello world” with one function call

The ## Examples section contains multiple self-contained sample programs, each under its own ### <descriptive name> subsection. Every example must:

• Be a complete program with a main() function that can be copied, compiled, and run
• Have compile/run instructions and expected output in a comment at the top
• Illustrate one specific technique, pattern, or gotcha

Good examples are concrete and illuminating: they show a real use case, a common mistake and its fix, or a non-obvious feature. A good rule of thumb: if a reader couldn't learn anything from the example that they couldn't get from reading the function signature, the example is too trivial.

The ## Implementation section shows how some of the most important functions or objects from the header could be implemented from scratch. This is the “how does it work under the hood” section. Each function gets its own ### <function name> subsection.

Implementation sections do not need to be production-quality — they should be readable and educational. A simplified strlen() that iterates a pointer is more valuable than an SIMD-optimised one if the goal is understanding. See assert.h for a good example.

After the Implementation section, optional sections can cover important topics that don't fit the above: configuration options, related functions from other headers, common pitfalls, historical context, comparison with alternatives, etc. The ## Disable section in assert.h is a good example.

Write in third-person encyclopedic style, but let the content be experiential. “A common mistake is…”, “The reason for this design is…”, “This is undefined behaviour because…” are all appropriate. Do not write dry function reference descriptions.

Every article should include at least one insight — something non-obvious that a programmer would benefit from knowing. Common sources of insight:

• Surprising behaviour (tm_year is years since 1900, not the actual year)
• Design rationale (why ctype.h functions take int not char)
• Security implications (gets() was removed in C11)
• Performance considerations (clock() is CPU time, not wall time)
• Portability traps (wchar_t is 2 bytes on Windows, 4 on Linux)

All code blocks should have a comment header:

// Compile: gcc main.c -o main
// Run:     ./main
// Output:  expected output here

For code that needs flags: gcc -std=c11 -lm main.c -o main. The Output line should show actual expected output so the reader knows if their compilation succeeded.