How consistent should `PascalCase` vs lowercase naming be in `std`?

Explain
1

In Zig’s standard naming convention (and in many places in std) there is a clear structure:

  • StructName in the declaration of a struct
  • struct_name (or similar lowercase) in usage of that struct

A capitalized CamelCase name signals a type, while the lowercase form signals a value.

For example, inconsistencies like this appear (LSP data):

fn parse(gpa: Allocator, source: [:0]const u8, mode: Mode) Allocator.Error!Ast
(fn (Allocator, [:0]const u8, Mode) error{OutOfMemory}!Ast)

// Go to Allocator | Mode | Ast
// Result should be freed with tree.deinit() when there are
// no more references to any of the tokens or nodes.

or this (LSP data):

fn deinit(tree: *Ast, gpa: Allocator) void

// (fn (*Ast, Allocator) void)

// Go to Ast | Allocator

Here the returned type is Ast, but the documentation refers to it as tree without ever stating that this is just a local variable name choice.

In effect, this part of std implicitly treats tree as the canonical name for an Ast value, without explaining why.

This is workable because “AST” is well known to stand for “Abstract Syntax Tree”, but in how Zig usually wants things named, it feels more natural to write ast than tree.

User code examples:

    // What std want
    const tree = try std.zig.Ast.parse(alloc, file_data, .zig);

    // What I see as more in line with zig naming convention 
    const ast = try std.zig.Ast.parse(alloc, file_data, .zig);

This is not just a simple change from tree to ast, since large parts of std here assume that tree is the better name.

Questions:

  1. Have I misunderstood how Zig naming structure should work, or is this one of the inconsistencies in std?
  2. I don’t think this is the only place where this happens in std. Should this be accepted as-is, or should there be a unification where possible, so that local variable usage of a struct inherits its type name (e.g. Ast → ast), at least in function signatures and documentation comments?
2

Hey, the language is still pre 1.0, but there is a long term goal of polishing the std once the language is in a 1.0 state, in the meantime the std is just a collection of utilities and data structures first and foremost designed for the compiler, those sorts of inconsistencies are to be expected, in the future you may be able to raise an issue about it, to get it fixed, in the meantime it’s just a minor inconsistency, also I don’t believe Zig really forces you by convention to name your variable as the lowercase equivalent of the PascalCase type, i think you can do whatever you want and it will be fine :slight_smile:

1 Like
3

tree is more distinct than ast which can easily be confused with Ast. I don’t think it matters much, but I do try to be mindful of those that have more trouble visually identifying things.

1 Like