Apple Comments With Architecture Diagrams

Level 1: A Map Inside The Code

This is like opening a recipe and finding not only the steps, but also a little map showing where every ingredient comes from and who carries it to the kitchen. The funny part is that many programmers write tiny notes, while this code has a whole instruction poster inside it.

Level 2: Why The Comment Helps

Swift is Apple's programming language used across many Apple platforms and open-source tools. DocC is Apple's documentation system, and the screenshot appears to show code related to resolving links between documentation pages. Link resolution means taking a reference and figuring out what page, symbol, or external destination it should point to.

The large ASCII diagram is useful because link resolution is not a single local function call. The visible boxes show a documentation context registering a bundle, resolving links, using an out-of-process resolver, requesting information from a server, and writing linkable entities. That is a lot of behavior to infer from code alone.

For a junior developer, this is the difference between a weak comment and a strong one. A weak comment says // set title right above title = value. A strong comment explains the system boundary, the reason for a design, or the contract another part of the system depends on. This screenshot is funny because it is dramatically more thorough than the comments most teams actually maintain.

Level 3: Comments With Load-Bearing Diagrams

The screenshot starts like normal Swift source:

import Foundation
import Markdown
import SymbolKit

Then it swerves into a full architecture note. The comment begins with Link resolution works in two parts: and proceeds to diagram DocC, a backend endpoint, an out-of-process resolver, server requests, other sources, and conversion steps like writing linkable entities. Below that, the actual code defines:

public struct LinkDestinationSummary: Codable, Equatable

The joke is scale. Most developers feel virtuous after adding // handle edge case. This screenshot shows a comment block that behaves like a miniature design document, complete with an ASCII sequence/flow diagram. The post text compares ordinary commenting habits against Apple's open-source style, and the image backs it up: this is not a comment explaining what one line does; it explains why several moving parts exist and how they communicate.

That matters because good documentation is not just more words. The best comments preserve context that the code cannot express locally: why link resolution is split, what data crosses process boundaries, what external references require, and what future maintainers must not accidentally break. The code can show a struct with properties like kind, language, path, referenceURL, title, and abstract; it cannot, by itself, show the system choreography that makes those fields necessary.

The funny sting is that this level of commenting makes everyone else's "self-documenting code" speech sound a little underfunded. Sometimes code is clear, and sometimes the architecture needs a map because the architecture is, inconveniently, architecture.