Self-Documenting Code Practices

Apply these practices to create code that documents itself through quality design and style.

Documentation Types

Definition: Information located outside source code listings, typically separate documents or Unit Development Folders (UDF)
Unit Development Folder (UDF) / Software Development Folder (SDF):
- Informal documentation containing developer notes during construction
- Primary purpose: provide clues about design decisions not recorded elsewhere
- Contents: copies of relevant requirements, top-level design sections, development standards, current code listings, design notes
Detailed Design Document: Low-level design document describing class-level or routine-level design decisions

Definition: Documentation located within the program listing itself
Characteristics: Most detailed documentation type, at source statement level
Advantage: Most closely tied to code, most likely to remain correct when code is modified

Core principle: The primary contributor to code-level documentation is not comments, but good programming style.

Components of good programming style:

Goal: Achieve "self-documenting code" where the code itself carries most of the documentation burden.

Effect: Good programming style makes code meaning obvious without relying on extensive comments.

When to apply: When designing or reviewing classes

Verify the following points:

Abstraction consistency: Does the class interface present a consistent abstraction?
Naming accuracy: Is the class well-named, describing its core purpose?
Interface intuitiveness: Does the class interface clearly indicate how to use it?
Abstraction level: Is the interface abstract enough that users don't need to consider implementation details?
Black-box property: Can the class be treated as a black box?

Action: If any answer is "no," refactor the class design.