风格指南
编译器不会强制这些编码约定,但文档随编译器一同提供这些约定,作为需要引用公认 Zig 编码风格规范时的参考依据。
避免名称冗余
避免在类型名称中使用以下词语:
- Value(值)
- Data(数据)
- Context(上下文)
- Manager(管理器)
- State(状态)
- utils、misc 或某人的姓名首字母
一切都是值,所有类型都是数据,一切都有上下文,所有逻辑都在管理状态。使用适用于所有类型的词语无法传达任何具体信息。
想使用 "utilities"、"miscellaneous" 或某人姓名首字母命名,说明没有正确分类,或者更常见的是过度分类。这些声明可以直接位于需要它们的模块根部,无须额外命名空间。
避免完全限定命名空间中的名称冗余
编译器会为每条声明分配一个完全限定命名空间,形成树状结构。应基于完整命名空间选择名称,避免冗余的名称片段。
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 等既定约定时,应遵循既定约定。
示例
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 标准库。