Ivan's wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# Writing guide on header files
**Writing guide on header files** is a supplement to the [[writing-guide|writing guide]] specifically for articles about C and C++ header files.

The goal of a header article is **not** to replicate documentation. [[https://en.cppreference.com|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.

## Article structure

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
```

### Title and description

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.

### Motivation

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?"

### Usage

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

### Examples

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.

### Implementation

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.

### Miscellaneous sections

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.

## Tone and content

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)

## Code block format

All code blocks should have a comment header:
```c
// 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.