代码规范
为规范模组开发过程,编制此文档。
2023 年 12 月 20 日修订。
命名风格
【强制】 所有代码中的命名应当使用英文,除了一些专有名词没有英文对应翻译的。
正例:QingGui
(青珪,一种上尖下方的玉质礼器)
反例:ModWuPin
(模组物品)【强制】 所有的类命名均使用 PascalCase(又称大驼峰、CapitalCamelCase 或 UpperCamelCase)风格。
正例:ModClass
【强制】 所有的接口命名以大写字母 I 开头。
正例:IPlayerCapabilityHolder
【强制】 在 API 中对外开放的抽象类命名以单词 Abstract 开头;在实现中的抽象类(不应被使用该 API 的类继承的)以 Base 结尾。
正例:AbstractBlockStateProvider
、BlockStateProviderBase
反例:BaseBlockState
【强制】 异常类命名以单词 Exception 结尾;测试类命名以要测试的类的名称开始,以单词 Test 结尾。
【强制】 方法名、参数名、成员变量、局部变量的命名都统一使用 camelCase(又称小驼峰、lowerCamelCase)风格。
正例:paramValue
、onUse()
、serverId
【强制】 常量命名均使用 MACRO_CASE(又称 CONSTANT_CASE 或 SCREAM_CASE)风格。
【强制】 枚举类的成员命名同常量命名。
【强制】 包名统一使用小写,点分隔符之间有且仅有一个英语单词(如果必须要两个及以上单词才能表达完整含义,使用 camelCase)。
说明: 若专有名词不是一个英语单词,如模组 ModID、组织名称等,也视为一个单词。
正例:games.moegirl.sinocraft.sinocore
、cx.rain.mc.icon_at_night
【强制】 禁止使用不规范的英文缩写,如果难以找到合适的缩写,请使用完整的名称。
反例:Abstract
缩写成Abs
【推荐】 最外层包名采用域名反写的形式,项目所有者最好持有该域名。
说明: 可能会用于避免潜在的版权问题。若是非 ASCII 的一级域名,请使用 Punycode 转换,包含横杠(又称连字符,-)的用下划线替代。【推荐】 在常量和变量命名时,表示其取值的性质的单词放在末尾,以增加可读性。
正例:startTime
、playerList
、MAX_THREAD_COUNT
反例:startAt
、listPlayer
、MAX_THREADS
【推荐】 如果模块、类、接口、方法使用了设计模式,在命名时要体现出具体模式。
正例:StringDecorator
、NmsFactory
【强制】 模组中用于注册游戏内容的类命名以 Mod 或者模组 ID 的缩写开头,后接注册的游戏内容名称(如 Block、Item)。
正例:ModBlocks
、SCItems
【强制】 模组中的游戏内容类,命名应以游戏内容的名称结尾。
正例:KnifeItem
、StoveBlock
【强制】 模组中用于逻辑服务端和逻辑客户端通信的类命名以传输方向(S2C、C2S)开头,以 Packet 结尾。
正例:C2SSaveDrawingPacket
【强制】 枚举类的命名以 Enum 结尾。
常量定义
【强制】 使用类型和中括号紧邻的方式(Java 风格)定义数组。
正例:int[] intArray;
反例:String args[];
【强制】 长整数类型的字面量,数值后使用大写的 L ,禁止使用小写的 l。 说明:小写 l 在一些字体下容易和数字 1 混淆,造成误解。
【强制】 浮点数类型的字面量,单精度的数值后面使用大写的 F ,双精度的数值后面不加 D(因为 Java 默认为双精度浮点数)。
【强制】 当被调用方法的形参为浮点数类型,且实参恰好是整数的时候,不要额外加小数部分,让 Java 自动隐式转换。
正例:Box.shape(1, 1, 1, 15, 15, 15);
反例:Box.shape(1.0F, 1.0F, 1.0F, 15.0F, 15.0F, 15.0F);
【推荐】 如果变量值仅在一个有限且大小可枚举的固定范围内变化,使用枚举类型定义。
代码格式
【强制】 左花括号前不换行,左花括号后换行;右花括号前换行,右花括号后如果是 else 等代码不换行,否则必须换行。
【强制】 如果仅有一行代码,也应当用花括号包围。
【强制】 左圆括号与其右侧的相邻字符之间不加空格,右圆括号与其左侧的相邻字符之间不加空格;右圆括号和左花括号之间要加空格。
【强制】 Java 语言中用于执行控制的保留字(如 if / for / while / switch / do)与左右圆括号之间都必须加空格。
【强制】 任何二目、三目运算符的左右两侧都要加一个空格。
【强制】 采用四个空格缩进,禁止使用 Tab 字符缩进。