本文规定 FluffOS 源码树中 LPC 代码的统一风格,适用于 testsuite/ 游戏库和示例代码,也可作为其他游戏库的默认编码规范。

本指南遵循 Google C++ 风格指南 的基本理念。驱动自身的 C++ 源码也采用该规范,其 src/.clang-format 配置以 Google 风格为基础,使用 2 个空格缩进,单行上限为 100 列。同时,本指南参考了社区广泛采用的 C 语言规范,例如 MaJerle/c-code-style,并针对 LPC 与 C 的差异进行了调整。

以下两项原则优先于所有具体规则:

  1. 优先考虑阅读者。
    代码被阅读的次数远多于被编写的次数。一条规则是否值得采用,取决于它能否降低后续阅读的成本。

  2. 沿用周围代码的风格。
    修改已有文件时,与现有代码保持一致比遵守本文更重要。这也是 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 使用此方式

格式化工具会拒绝写入不满足以下条件的文件:

  • 输出与输入在词法单元层面等价。
  • 字面量的字节内容完全不变。
  • 格式化结果具有幂等性,即再次格式化不会产生变化。

因此,可以放心运行格式化工具。有关命令选项、编辑器集成,以及工具会修改和保留哪些内容的详细说明,请参阅格式化工具文档。