|
| 1 | +MCP Naming Rules & Conventions |
| 2 | +============================== |
| 3 | + |
| 4 | +> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). |
| 5 | +
|
| 6 | +Introduction |
| 7 | +------------ |
| 8 | +In order to guarantee a consistent style and theme across MCP names, the following conventions |
| 9 | +SHOULD be adhered to when mapping new things or proposing replacements for existing mappings. |
| 10 | + |
| 11 | +Current mappings MAY deviate from this scheme, but you MUST NOT follow their naming convention when proposing new names. Instead you SHOULD try to fix the old names. |
| 12 | + |
| 13 | +Please refer to this document whenever you do not know how to format or structure a name. |
| 14 | + |
| 15 | +Getting Started |
| 16 | +--------------- |
| 17 | + - **If you do not know what to name something then *you SHOULD NOT name it*. Let someone else do so.** |
| 18 | + - Names SHOULD reflect intent, *not* solely implementation. Check usages rather than looking only at the definition. |
| 19 | + Also consider overrides and their context. |
| 20 | + - Names SHOULD be concise and memorable, while redundancies SHOULD be avoided. If information can be inferred from context (type, parameters etc.), |
| 21 | + do not include it in the name. This especially applies to fields and methods in a class, where you do not |
| 22 | + need to have the defining class's name in the member's name. |
| 23 | + - Clarification SHOULD preferably reside in the documentation comment, not in verbose names. Conversely, you SHOULD NOT give fields, methods, or method parameters needless comments that only repeat signature and name. Instead, use the documentation |
| 24 | + for non-trivial examples or technical details. |
| 25 | + |
| 26 | +General |
| 27 | +------- |
| 28 | + - All names MUST use American English spelling. |
| 29 | + - Acronyms SHOULD generally be written all-lowercase, while normal camel case rules still apply. |
| 30 | + For instance, "identifier" becomes `id` as standalone word or at the beginning of a camel case phrase and |
| 31 | + `Id` when used within a phrase.<br> |
| 32 | + There are various exceptions to this rule which apply only when the word does not start with them: |
| 33 | + - axis-aligned bounding boxes: `AxisAlignedBB` → `AABB` |
| 34 | + - named binary tags → `NBT` |
| 35 | + - red, green, blue (and alpha) color components → `RGB(A)` |
| 36 | + - universally unique identifiers: `UUID` → `UniqueId` |
| 37 | + |
| 38 | +### Examples |
| 39 | + - A class for RGB values SHOULD be called `RGBColor`, not `RgbColour`. |
| 40 | + - A method for adding something to a container SHOULD be called `Container.add`, not `Container.addToContainer`, as that information can be inferred from the class name. |
| 41 | + |
| 42 | +Type Names |
| 43 | +---------- |
| 44 | + - Type names MUST be named in `UpperCamelCase`. |
| 45 | + - Classes, interfaces etc. MUST follow a suffix-based naming scheme. |
| 46 | + Specifically, this means for any name, `NameType` would be the correct name, where `Type` SHOULD be |
| 47 | + derived from the supertypes. |
| 48 | + - Abstract base classes SHOULD be prefixed with `Abstract`. |
| 49 | + - Interfaces MUST be prefixed with the letter `I`. |
| 50 | + - Enums SHOULD be named directly after the things they are enumerating, in singular form. |
| 51 | + There MUST NOT be an `Enum` prefix/suffix. |
| 52 | + |
| 53 | +### Examples |
| 54 | + - For a new shelf block with an inventory, appropriate names would be `ShelfBlock`, `ShelfTileEntity` and |
| 55 | + `ShelfContainer`. |
| 56 | + - An enumeration for dye colors would be called `DyeColor`. |
| 57 | + |
| 58 | +Field Names |
| 59 | +----------- |
| 60 | + - Instance and non-final static fields MUST follow the `camelCase` scheme. |
| 61 | + - `final static` fields (constants) MUST use `CONSTANT_CASE`. |
| 62 | + - `boolean` type fields SHOULD NOT start with an *is* prefix unless there is a convincing reason to do so. |
| 63 | + - Field names MUST NOT use prefixes or suffixes like `the` or `Obj`. |
| 64 | + |
| 65 | +Method Names |
| 66 | +------------ |
| 67 | + - Methods MUST be named using `camelCase`. |
| 68 | + - Method names SHOULD always start with a verb. Standard conventions for setters and getters apply. |
| 69 | + - Getter-style methods returning a `boolean` SHOULD be named with a phrase that can be used |
| 70 | + in a conditional (if) clause, e.g. some verb or adjective prefixed with some third person verb. |
| 71 | + Common prefixes include `is`, `can`, `has`, and `contains`. |
| 72 | + - 'Event handling' methods SHOULD follow an `on<Noun>` theme where the noun is the event's name |
| 73 | + (with redundancies removed). |
| 74 | + - Methods which store an object's state in a provided container SHOULD be prefixed with `write`. |
| 75 | + This especially applies to methods that write to some NBT tag or the network buffer. |
| 76 | + - Methods which retrieve an object's state from a provided container and apply it to an existing instance |
| 77 | + SHOULD be prefixed with `read`. This especially applies to methods that read from an NBT tag or |
| 78 | + the network buffer. |
| 79 | + - Methods which convert an object's state into some storage format or reconstruct an object from a given |
| 80 | + storage container SHOULD have a `deserialize` or `serialize` prefix accordingly. |
| 81 | + This applies to methods that perform conversions from an object into JSON/NBT and back, |
| 82 | + without manipulating some provided container or existing object instance. |
| 83 | + |
| 84 | +### Examples |
| 85 | + - A boolean getter to check whether a chest was opened in the last few seconds SHOULD be called `wasOpenedRecently`. |
| 86 | + - The method for handling block right clicks SHOULD be called `onActivation` (noun form, no redundancy), |
| 87 | + not `onBlockActivated` (past participle, redundant `Block` infix). |
| 88 | + |
| 89 | +Method Parameter Names |
| 90 | +---------------------- |
| 91 | + - Parameters MUST follow the `camelCase` scheme. |
| 92 | + - If a name clashes with that of a field or a type name, it SHOULD be suffixed with `In`. |
| 93 | + - Parameters of certain types SHOULD get named according to the following list: |
| 94 | + - `BlockPos` arguments SHOULD be named `pos` when the usage is obvious and `<subject>Pos` when |
| 95 | + there is ambiguity, multiple parameters or the parameter is known to represent something that can not be gleaned from the method name. |
| 96 | + - Parameters of the `IWorldReaderBase` and related types SHOULD be called `worldIn`. You MAY name it differently if the parameter has a known purpose. |
| 97 | + |
| 98 | +### Examples |
| 99 | + - The `World` parameter to a method like `Block.onActivation` SHOULD be called `worldIn`. |
| 100 | + - The two `BlockPos` parameters to a method that calculates the volume of a block cuboid SHOULD be called `startPos` and `endPos`. |
0 commit comments