跳转到内容
语言参考Zig 0.17.0官方原文

编译器不会强制这些编码约定,但文档随编译器一同提供这些约定,作为需要引用公认 Zig 编码风格规范时的参考依据。

避免名称冗余

避免在类型名称中使用以下词语:

  • Value(值)
  • Data(数据)
  • Context(上下文)
  • Manager(管理器)
  • State(状态)
  • utils、misc 或某人的姓名首字母

一切都是值,所有类型都是数据,一切都有上下文,所有逻辑都在管理状态。使用适用于所有类型的词语无法传达任何具体信息。

想使用 "utilities"、"miscellaneous" 或某人姓名首字母命名,说明没有正确分类,或者更常见的是过度分类。这些声明可以直接位于需要它们的模块根部,无须额外命名空间。

避免完全限定命名空间中的名称冗余

编译器会为每条声明分配一个完全限定命名空间,形成树状结构。应基于完整命名空间选择名称,避免冗余的名称片段。

redundant_fqn.zig
const std = @import("std");
pub const json = struct {
pub const JsonValue = union(enum) {
number: f64,
boolean: bool,
// ...
};
};
pub fn main() void {
std.debug.print("{s}\n", .{@typeName(json.JsonValue)});
}
命令行
$ zig build-exe redundant_fqn.zig
$ ./redundant_fqn
redundant_fqn.json.JsonValue

本例中,"json" 在完全限定命名空间中重复出现。解决方式是从 JsonValue 中删除 Json。这里有名为 json 的空结构体,但不要忘记文件名也构成完全限定命名空间的一部分。

本例是避免名称冗余规则的例外。类型含义已经精简至核心:它本身就是 JSON 值,再使用更具体的名称反而失真。

避免下划线前缀

一些编程语言常在标识符前添加下划线 _like_this,用来避免关键字冲突、名称冲突,或表示与标识符用法有关的额外信息,例如私有性、复杂数据不变量、不遵守语义化版本规则,或者特定上下文中的类型反射含义。

Zig 没有私有字段,本指南也不建议伪装成存在私有字段。应根据语义谨慎命名字段,并在文档中说明如何在不破坏数据不变量的前提下使用。如果某个字段不遵循其他部分相同的语义化版本规则,应在文档注释中注明例外。

对于类型反射,使用类型系统比赋予字段名称特殊含义更不易出错、更易维护。

对于名称冲突,下划线不足以解释两个原本相同名称之间的区别。如果不必担心混淆,本指南建议外层作用域使用更完整的名称,内层作用域使用更简短的名称。

最后,最好通过字符串标识符语法避免关键字冲突。

空白字符

  • 使用 4 个空格缩进
  • 除非需要换行,否则左花括号放在同一行。
  • 列表超过两项时,每项单独一行,并利用末尾可加逗号这一便利。
  • 行宽尽量控制在 100 个字符以内,结合实际合理判断。

命名

大致为 camelCaseFunctionName、TitleCaseTypeName、snake_case_variable_name。更准确地说:

  • 如果 x 是没有字段、且永远不打算实例化的 struct,那么 x 被视为“命名空间”,应采用 snake_case。
  • 如果 x 是 type 或 type 的别名,那么 x 应采用 TitleCase。
  • 如果 x 可以调用,且 x 的返回类型为 type,那么 x 应采用 TitleCase。
  • 如果 x 可以调用但不满足上述情况,那么 x 应采用 camelCase。
  • 其他情况下,x 应采用 snake_case。

缩略词、首字母缩写、专有名词,以及其他在英语书写中具有大小写规则的词,都与普通词语一样服从命名约定。即使只有两个字母的缩写也不例外。

文件名分为类型和命名空间两类。如果文件(隐式结构体)包含顶层字段,应与其他有字段的结构体一样,使用 TitleCase 命名;否则使用 snake_case。目录名使用 snake_case。

这些是通用经验规则;如果其他方式更合理,就采用合理方式。例如,存在 ENOENT 等既定约定时,应遵循既定约定。

示例

style_example.zig
const namespace_name = @import("dir_name/file_name.zig");
const TypeName = @import("dir_name/TypeName.zig");
var global_var: i32 = undefined;
const const_name = 42;
const PrimitiveTypeAlias = f32;
const StructName = struct {
field: i32,
};
const StructAlias = StructName;
fn functionName(param_name: TypeName) void {
var functionPointer = functionName;
functionPointer();
functionPointer = otherFunction;
functionPointer();
}
const functionAlias = functionName;
fn ListTemplateFunction(comptime ChildType: type, comptime fixed_size: usize) type {
return List(ChildType, fixed_size);
}
fn ShortList(comptime T: type, comptime n: usize) type {
return struct {
field_name: [n]T,
fn methodName() void {}
};
}
// 在 Zig 标识符中使用 XML 时,不保留原来的大写形式。
const xml_document =
\\<?xml version="1.0" encoding="UTF-8"?>
\\<document>
\\</document>
;
const XmlParser = struct {
field: i32,
};
// 首字母缩写 BE(Big Endian,大端)在 Zig 标识符名称中只是普通词语。
fn readU32Be() u32 {}

更多示例参见 Zig 标准库。

文档注释指南

  • 省略根据被说明对象的名称即可得知的冗余信息。
  • 鼓励在多个相似函数上重复信息,因为这有助于集成开发环境和其他工具提供更好的帮助文本。
  • 使用 assume 表示这样的不变量:一旦违反,就会产生不进行检查的非法行为。
  • 使用 assert 表示这样的不变量:一旦违反,就会产生带安全检查的非法行为。