本文规定 FluffOS 源码树中 LPC 代码的统一风格,适用于 testsuite/ 游戏库和示例代码,也可作为其他游戏库的默认编码规范。
本指南遵循 Google C++ 风格指南 的基本理念。驱动自身的 C++ 源码也采用该规范,其 src/.clang-format 配置以 Google 风格为基础,使用 2 个空格缩进,单行上限为 100 列。同时,本指南参考了社区广泛采用的 C 语言规范,例如 MaJerle/c-code-style,并针对 LPC 与 C 的差异进行了调整。
以下两项原则优先于所有具体规则:
-
优先考虑阅读者。
代码被阅读的次数远多于被编写的次数。一条规则是否值得采用,取决于它能否降低后续阅读的成本。 -
沿用周围代码的风格。
修改已有文件时,与现有代码保持一致比遵守本文更重要。这也是 MaJerle C 语言指南中最重要的一条规则。
下面的排版规则由 LPC 格式化工具 自动执行。运行 testsuite/format.sh 即可应用这些规则;CI 会拒绝未按规范格式化的测试库代码。命名与编程实践规则则需要开发者自行判断,格式化工具不会修改这些内容。
排版规则(由格式化工具执行)
缩进与行长度
- 每级缩进使用 2 个空格,禁止使用制表符。
- 每行最多 100 列,与驱动 C++ 配置中的
ColumnLimit一致。过长的语句会在最外层括号组内换行,每个元素单独一行。以下三类内容不受此限制,因为拆分它们可能改变程序行为或含义:字符串、模板字符串和 heredoc 字面量;注释;带有行尾注释的整行。 - 预处理指令从第 0 列开始,不缩进。
#include和inherit保持原有顺序。后面的#include不会被移动到inherit前面。例如,对象文件的头部通常依次为#include <ansi.h>、inherit NPC;、#include "fight.h"。不要对包含指令排序或重新分组。
花括号
统一使用 K&R 风格:左花括号与声明或关键字位于同一行;else 和 do 循环的 while 紧接在右花括号所在行:
int find(string name) {
if (!name) {
return -1;
} else {
return lookup(name);
}
}
do {
step();
} while (more());
- 完全为空的代码块写成
{},例如void create() {}。 - 建议为所有控制流语句体添加花括号;但如果语句体只有一条语句,且单独占一行,可以省略:
if (!raw)
return mask[0];
空格
| 场景 | 规则 | 示例 |
|---|---|---|
控制流关键字与 ( 之间 |
一个空格 | if (x)、while (x)、for (;;)、foreach (v in arr)、return (x) |
函数调用与 ( 之间 |
不留空格 | write(msg)、funcs[0](5, 5)、f(a)(b) |
| 类似函数调用的关键字 | 不留空格 | catch(err)、new("/obj") |
| 圆括号内部 | 不添加首尾空格 | f(a, b),不要写成 f( a, b ) |
| 二元运算符、赋值运算符 | 两侧各一个空格 | a = b + c * d、a >>= 2 |
| 三元运算符 | 两侧留空格 | a ? b : c |
| 一元运算符 | 紧贴操作数 | -a、!ok、~bits、++i、i++ |
| 逗号、分号 | 前面不留空格,后面留一个空格 | f(a, b);for (i = 0; i < n; i++) |
| 类型转换 | 紧贴操作数 | (string)x、(mixed *)arr、return (int)v |
| 下标访问 | 不留空格 | arr[0]、m["key"]、s[1..<2] |
->、限定符 :: |
两侧不留空格 | ob->query()、efun::write() |
数组声明中的 * |
紧贴名称 | string *names、int *fn(mixed *args) |
| 数组字面量 | 分隔符内侧留空格,空数组除外 | ({ 1, 2, 3 }),空数组为 ({}) |
| 映射字面量 | 分隔符内侧留空格,键紧贴冒号 | ([ "a": 1, "b": 2 ]),空映射为 ([]) |
| 函数字面量 | 两端分隔符内侧留空格 | (: f :)、(: $1 + $2 :) |
| 默认参数的冒号 | 冒号前不留空格 | void f(int a, string b: (: "x" :)) |
| 展开运算符 | 紧贴前面的表达式 | f(args...);独立使用时为 f(int a, ...) |
| 标签的冒号 | 紧贴标签 | case 1:、default:、private: |
行尾 // 注释 |
与代码至少间隔两个空格 | return 1; // 原因说明 |
其中两项规则特意与 C++ 配置不同,因为相关语法在 LPC 中具有不同含义:
string *names:LPC 的*是数组标记,不是指针。绝大多数游戏库代码都将它紧贴名称书写。驱动的 C++ 配置则使用PointerAlignment: Left,写成type* name。({ ... })和([ ... ]):保留分隔符内侧的空格,而 C++ 花括号初始化列表不添加这种空格。LPC 的分隔符由两个字符组成,添加空格有助于辨认成对的分隔符。
分支标签
case 和 default 在 switch 内缩进一级,分支语句体再缩进一级,与 Google 的 IndentCaseLabels 规则一致:
switch (x) {
case 1:
handle_one();
break;
case LOW..HIGH: // LPC 范围标签
handle_range();
break;
default:
handle_rest();
}
保留源码中的换行布局
与 clang-format 不同,格式化工具不会重新决定换行位置。它会保留原有布局,仅在超出列数限制时拆分长行:
-
原本写在一行内的代码块,只要没有超长,就继续保持单行:
void event_ping(object from, int v) { origin = from; value = v + 1; } -
已经分成多行的调用或声明会保留原有布局,包括结束符的位置。紧接最后一个参数的
");不会被另起一行;});也会继续紧贴函数式参数或内联代码块参数的右花括号。 -
连续空行的数量原样保留。可以用空行分隔相关语句组,函数之间留一个空行。
-
注释不会被移动到其他行,行尾注释也不会导致前面的代码被强制换行。
手写测试代码的布局本身承载着意图,格式化工具会尊重这些信息。
命名规范
从测试库现有代码来看,LPC 的主流命名习惯更接近 C 语言。它特意区别于 Google C++ 的 CapitalizedWords 风格,因为 LPC 标识符历来以小写为主。
| 对象 | 命名规则 | 示例 |
|---|---|---|
| 函数、驱动回调、efun 覆盖实现 | lower_snake_case |
query_name()、do_tests() |
| 局部变量、全局变量 | lower_snake_case |
save_file、num_users |
宏、#define 常量 |
ALL_CAPS_WITH_UNDERSCORES |
MAX_USERS、TUI_ANSI |
| 源文件 | lower_snake_case.lpc |
hot_reload.lpc |
| 类 | 全小写或首字母大写,同一文件内保持一致 | class point、class Counter |
| 头文件 | lower_snake_case.h |
tests.h |
- 不要自行引入匈牙利命名法前缀,或
m_之类的成员标记。LPC 对象通常足够精简,使用普通名称并配合private即可。 - 根据含义命名,而不是根据类型命名。例如使用
users,而不是user_array。
可见性与代码结构
- 默认使用
private。 不属于对象对外接口的全局变量和辅助函数应声明为private。在现有代码中,private的使用次数超过public的 20 倍。nomask应保留给涉及关键安全逻辑、禁止继承者覆盖的函数。 - 在满足需要的最小作用域内声明局部变量,并在声明时初始化。FluffOS 允许在语句之后声明变量,因此应优先在首次获得值的位置声明,而不是采用 C89 风格,将所有声明集中放在代码块顶部。
- 初始化表达式需要分别关注时,每行只写一条声明。没有初始化的同类型局部变量可以合并声明,例如
int i, j, n;。 - 不需要索引时,优先使用
foreach (member in aggregate),而不是按索引遍历的for循环。 - 如果
switch不能从结构上保证覆盖所有情况,就应提供default:分支。 - 优先通过返回值传递结果,而不是通过
ref参数写入结果。只有调用方确实需要原地修改多个结果时,才使用ref。
注释
- 单行注释和行尾说明使用
//,较长的块注释使用/* ... */。MaJerle 的 C 语言规范为了兼容 C89 禁止使用//,但 LPC 一直支持这两种注释,应选择更便于阅读的形式。 - 注释应解释为什么这样做。重复下一行代码含义的注释只会增加阅读负担;记录代码本身无法表达的约束,才有实际价值。
- 行尾注释与代码至少间隔两个空格。如果手动对齐了一组行尾注释,格式化工具会保留这种对齐。
预处理器使用规范
以下 C 语言规则同样适用于 LPC 预处理器:
-
宏参数和整个展开表达式都应加括号:
#define SQUARE(x) ((x) * (x)) -
多语句宏使用
do { ... } while (0)包裹,使其在if、else中表现为一条语句。 -
头文件使用
#ifndef NAME_H、#define NAME_H和#endif防止重复包含。 -
如果条件以后可能扩展为多个判断项,优先使用
#if defined(XYZ),而不是#ifdef XYZ。 -
测试代码和可选功能包代码,应使用对应的功能包条件宏进行保护,例如
#ifdef __PACKAGE_ASYNC__。
LPC 中还有一项需要特别注意:对参数进行字符串化的宏,会将实参在源码中的原始写法直接写入程序输出。例如:
#define STR(x) #x
调用 STR(1+2) 得到的字符串是 "1+2"。格式化工具会识别这种情况,不调整相关实参中的空格;手动编写或修改时也应注意。
错误处理
catch(...)返回错误信息或0。应检查其结果,或者明确选择忽略。需要引发错误时,使用error("message"),不要直接使用throw。-
不要用不可信输入构造格式字符串,而应将其作为参数传入:
printf("%s", player_text);
执行与检查
testsuite/format.sh # 直接格式化测试库代码
testsuite/format.sh --check # 仅检查;CI 使用此方式
格式化工具会拒绝写入不满足以下条件的文件:
- 输出与输入在词法单元层面等价。
- 字面量的字节内容完全不变。
- 格式化结果具有幂等性,即再次格式化不会产生变化。
因此,可以放心运行格式化工具。有关命令选项、编辑器集成,以及工具会修改和保留哪些内容的详细说明,请参阅格式化工具文档。