Why are allocator interfaces and implementations split across `std.mem` / `std.heap`, while IO is colocated under `std.Io`?

I think abbreviations are fine.

The main thing to consider with abbreviations is first-time discoverability. In Zig, first contact usually happens through the LSP, and for some users through the documentation. Those are the two primary places where people learn what something is.

If an abbreviation is used, it is important that the doc comment spells out the full name clearly. Abbreviations are excellent for long-term users because they compact code and reduce visual noise, but they must be consistent across std and remain within a high standard of readability.

Using common and correct English abbreviations also helps readability. Made-up or inconsistent abbreviations increase friction rather than reduce it.

A rough LSP-style example of what I mean:

std.alloc

/// Allocator (alloc)
/// Collection of allocator implementations and related utilities.

This thread is also relevant, since single-letter naming is effectively a form of abbreviation and raises similar discoverability concerns:
https://ziggit.dev/t/zig-api-naming-single-letter-generics-with-no-explanation/13539

1 Like