Style Guide

These coding conventions are not enforced by the compiler, but they are shipped in this documentation along with the compiler in order to provide a point of reference, should anyone wish to point to an authority on agreed upon Zig coding style.

Whitespace

  • 4 space indentation
  • Open braces on same line, unless you need to wrap.
  • If a list of things is longer than 2, put each item on its own line and exercise the ability to put an extra comma at the end.
  • Line length: aim for 100; use common sense.

Names

Roughly speaking: camelCaseFunctionName, TitleCaseTypeName, snake_case_variable_name. More precisely:

  • If x is a type then x should be TitleCase, unless it is a struct with 0 fields and is never meant to be instantiated, in which case it is considered to be a “namespace” and uses snake_case.
  • If x is callable, and x‘s return type is type, then x should be TitleCase.
  • If x is otherwise callable, then x should be camelCase.
  • Otherwise, x should be snake_case.

Acronyms, initialisms, proper nouns, or any other word that has capitalization rules in written English are subject to naming conventions just like any other word. Even acronyms that are only 2 letters long are subject to these conventions.

File names fall into two categories: types and namespaces. If the file (implicitly a struct) has top level fields, it should be named like any other struct with fields using TitleCase. Otherwise, it should use snake_case. Directory names should be snake_case.

These are general rules of thumb; if it makes sense to do something different, do what makes sense. For example, if there is an established convention such as ENOENT, follow the established convention.

Examples

style_example.zig

  1. const namespace_name = @import("dir_name/file_name.zig");
  2. const TypeName = @import("dir_name/TypeName.zig");
  3. var global_var: i32 = undefined;
  4. const const_name = 42;
  5. const primitive_type_alias = f32;
  6. const string_alias = []u8;
  8. const StructName = struct {
  9.     field: i32,
  10. };
  11. const StructAlias = StructName;
  13. fn functionName(param_name: TypeName) void {
  14.     var functionPointer = functionName;
  15.     functionPointer();
  16.     functionPointer = otherFunction;
  17.     functionPointer();
  18. }
  19. const functionAlias = functionName;
  21. fn ListTemplateFunction(comptime ChildType: type, comptime fixed_size: usize) type {
  22.     return List(ChildType, fixed_size);
  23. }
  25. fn ShortList(comptime T: type, comptime n: usize) type {
  26.     return struct {
  27.         field_name: [n]T,
  28.         fn methodName() void {}
  29.     };
  30. }
  32. // The word XML loses its casing when used in Zig identifiers.
  33. const xml_document =
  34.     \\<?xml version="1.0" encoding="UTF-8"?>
  35.     \\<document>
  36.     \\</document>
  37. ;
  38. const XmlParser = struct {
  39.     field: i32,
  40. };
  42. // The initials BE (Big Endian) are just another word in Zig identifier names.
  43. fn readU32Be() u32 {}

See the Zig Standard Library for more examples.

Doc Comment Guidance

  • Omit any information that is redundant based on the name of the thing being documented.
  • Duplicating information onto multiple similar functions is encouraged because it helps IDEs and other tools provide better help text.
  • Use the word assume to indicate invariants that cause Undefined Behavior when violated.
  • Use the word assert to indicate invariants that cause safety-checked Undefined Behavior when violated.