Update conventions

CONVENTIONS.md

@@ -14,6 +14,21 @@ To make code as easy to read as possible, keep names in the natural language ord
 block entity should be named `ChestBlockEntity` rather than `BlockEntityChest`. Though prefix naming may be helpful for
 grouping classes together in an IDE's tree view, reading and writing code is done much more often than browsing files.
 
+## Class names
+Except as noted below, class names should be a singular noun. Interface names should be a noun or an adjective (`Angerable`, `Nameable`).
+
+Classes and interfaces whose purpose is to hold instances or registry keys of `X` as `static final` fields should be named `Xs`. For example, `CatVariants` is an interface holding vanilla `CatVariant`s.
+A class whose purpose is to serve as a type of `X` should be named `XType`. Typically, `XType` is pre-defined, while an infinite amount of `X` can be created at runtime or loaded from resource packs. (Compare `EntityType` and `Entity`; note that many existing names violate this rule, such as `StatusEffect` (type) and `StatusEffectInstance` (instance).)
+
+Use `Manager` for a class whose instance manages specific behavior. These are usually attached to a server, client, world, or player.
+
+There are three naming conventions for helper-method classes (i.e. classes that are never instantiated and hold only static members). If the public methods exist for a single purpose, then that purpose, suffixed with "ing", can be used. Examples: `Dismounting`, `SaveLoading`, `BlockLocating`.
+When `X` is a name of another class, `Xs` can also be used to hold helper methods related to `X`, so long as it makes sense etymologically and that name has not already been used for holding instances of `X`. Examples: `Uuids`, `Codecs`, `Texts`, `Nullables`.
+In other cases, both `Util` and `Helper` suffixes are used.
+Try to avoid conflicts with libraries used by Mojang, such as Guava and Apache Commons.
+
+Do not name instantiable classes `Util` or `Helper`.
+
 ## Spelling
 
 Use American English for consistency throughout Yarn and with known Mojang names.
@@ -41,7 +56,9 @@ time to type thanks to IDE autocompletion. Common abbreviations you should use a
 
  - "id" for "identifier"
  - "pos" for "position"
+ - "vec" for "vector" (note: use "pos" when it denotes a position)
  - "nbt" for "named binary tag"
+ - "buf" for `ByteBuf` (used in networking; use "buffer" for NIO/LWJGL buffers used in client)
  - "init" for "initialize"
  - "min"/"max" for "minimum"/"maximum"
  - Any abbreviations used by Java or libraries ("json", "html", etc.)
@@ -52,8 +69,9 @@ Treat acronyms as single words rather than capitalizing every letter. This impro
 
 ## Packages
 
-Package names should always be singular to respect Java conventions. Try to respect the Mojang package structure to avoid
-visibility problems in the future.
+Package names should always be singular to respect Java conventions. Avoid creating new packages directly under `net.minecraft`.
+
+Client-only classes (i.e. those annotated as `@Environment(EnvType.CLIENT)`) must be placed under `net.minecraft.client` (or in some cases `com.mojang.blaze3d` or `net.minecraft.server.integrated`). Classes included in both jars must not be placed under those packages.
 
 ## Consistency
 
@@ -64,6 +82,7 @@ name patterns you should use.
 ### Ticks and updates
 
 Use "tick" for updates done once per tick. Use "update" for other kind of updates.
+Note that "tick" is used in block-related code for things that are not performed once per tick for historical reasons. For example, neither `randomTick` nor `scheduledTick` gets called once per tick.
 
 ### Value last tick
 
@@ -72,7 +91,11 @@ Use the word "last" for the value that something had last tick (`lastX`, `lastWi
 ### Getters, setters, withers, and creators
 
 Use "get" for non-boolean getters and other methods that calculate some property with no side effects other than caching a value
-in a private field. For boolean getters, use "is".
+in a private field. For boolean getters, use "is", "can", "should", and similar verbs (like "requires").
+
+Exception: record components should always be prefix-less, even if it means dropping the "get" prefix from the implementing interface.
+
+For more complex computations, "find" and "calc" are frequently used.
 
 Use "set" for methods that set some property. Name the parameter the same as the property (`setColor(color)`, not
 `setColor(newColor)`).
@@ -81,7 +104,8 @@ Use "with" for methods that return a copy of an object with a different value fo
 as the property.
 
 Use "create" for methods that create a new instance of some object. Use "get or create" for methods that create a new
-instance only if one does not already exist. Don't use "get or create" for lazy initialization, though. 
+instance only if one does not already exist. Don't use "get or create" for lazy initialization, though.
+For collection-like classes and other classes that hold contents, `of` is preferred over `create`. `of` methods can return a reused value (like with `List.of()`).
 
 ### Serialization
 
@@ -98,22 +122,31 @@ object passed as a parameter.
 
 Use "factory" for objects whose purpose is creating other objects.
 
-Use "builder" for objects whose purpose is helping with the creation of an immutable object. Name builder methods the same
-as the field they're setting, without any prefix.
+Use "builder" for objects whose purpose is helping with the creation of an immutable object. Name builder fields, methods, and params the same as the field they're setting, without any prefix.
+If a builder method adds to a list or puts to a map, then it should be named as the singular version of the field name. For example, a builder method that adds a value to `effects` list should be named `effect`.
+Name the object-creating method "build". Static methods that returns a builder should be named "builder".
 
 ### Collections
 
 Use a plural name for collections and maps rather than the words "list", "set", "array", etc., unless it's a collection of
 collections or there are several collections of different types containing the same objects (`entities`, `entityLists`).
 
-When it's enough, name maps based on the value type. Otherwise, name it in the "`valuesByKeys`" format.
+When it's enough, name maps based on the value type. Otherwise, name it in the "`keyToValue`" or "`valuesByKeys`" format.
 
 ### Coordinates
 
 Coordinates can be named `x`, `y`, and `z` when it's clear what they represent. If clarification is needed, add a word in
 front of the coordinate (`velocityX`, not `xVelocity`).
 
-Name screen coordinates `x` and `y`, rather than `left` and `top`.
+Refer to screen coordinates as `x` and `y` when inside rendering code such as `DrawContext`.
+This also applies to positions of screen widgets if they are specified using the topleft corner position, the height, and the width. If instead the positions of widgets are specified using 2 coordinates, use `left`, `top`, `right`, and `bottom` instead of `x1`, `y1`, `x2`, and `y2`.
+
+### Worlds
+Use "world" to describe the world with blocks and entities. Use "dimension" to describe the types of worlds that can be defined by data packs.
+
+There is no single convention on what to call the world save (a save data that contains multiple worlds, like the Overworld, the Nether, and the End). In many places this is referred to as "level", especially in `level.dat`-related code. (Examples: `LevelLoadingScreen`, `LevelProperties`, `LevelStorage`)
+In client GUI-related code, however, "world" is also used. (Examples: `CreateWorldScreen`, `SelectWorldScreen`, `WorldCreationSettings`)
+Server-side code generally refers to them as "save". (Examples: `SaveLoading`)
 
 ### Special classes
 
@@ -124,10 +157,17 @@ Unless a more descriptive name is better, these Minecraft classes should get spe
 | `net.minecraft.client.render.VertexConsumerProvider`   | `vertexConsumers` |
 | `net.minecraft.client.util.math.MatrixStack`           | `matrices`        |
 | `net.minecraft.registry.RegistryWrapper.WrapperLookup` | `registries`      |
+| Interfaces implemented by `World`                      | `world`           |
+
+### Other conventions
+- Methods that register the values and return the default value (i.e. `Registries.Initializer`) should be named `registerAndGetDefault` for static registries, and `bootstrap` for dynamic registries.
+- Use "draw" for drawing a simple shape, such as rectangles, cubes, texts, and a texture. Use "render" for drawing something more concrete, such as the sky, blocks, entities, particles, user interfaces, and buttons. A "render" method typically includes multiple "draw" calls.
+- Use `index` for numeric IDs assigned to `Enum`s.
+- Name methods `tryX` if it performs X conditionally. For example, a method that checks a spawn condition and only spawns an entity if it is satisfied should be named `trySpawn` (not `trySpawning`).
 
 ## Javadocs
 
-Write sentences for class, method and field javadocs, starting with an uppercase and ending with a period. Start method docs with verbs, like `Gets` or `Called`. Use HTML tags such as `<p>` if the docs have several paragraphs, as line wraps are converted to spaces in the generated documentation. Feel free to start a new line whenever you feel the current line is too long. Note that some ending tags such as `</p>` are not mandatory for Javadocs to render correctly.
+Write sentences for class, method and field javadocs, starting with an uppercase and ending with a period. Start method docs with verbs, like `Sets` or `Called`. Use HTML tags such as `<p>` if the docs have several paragraphs, as line wraps are converted to spaces in the generated documentation. Feel free to start a new line whenever you feel the current line is too long. Note that some ending tags such as `</p>` are not mandatory for Javadocs to render correctly.
 
 Parameter and `@return` documentation should use quick descriptions without initial capitalization or punctuation, such as `{@code true} if the block placement was successful, {@code false} otherwise`. `{@return}` used in the first sentence can duplicate enclosed text to the return description.
 
@@ -143,7 +183,7 @@ Since enigma format does not support `package-info.java` file creation, yarn kee
 
 ### Tooling
 
-Fabric-hosted Javadocs are generated using [JDK 16 Standard Doclet](https://docs.oracle.com/en/java/javase/16/docs/specs/javadoc/doc-comment-spec.html) and can use any feature it supports. For example, it has a [list of supported tags](https://docs.oracle.com/en/java/javase/16/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used). You can personally build the documentation with a newer Java version. See [the 'Checking Javadoc' section](#checking-javadoc) for how to build the documentation locally.
+Fabric-hosted Javadocs are generated using [JDK 21 Standard Doclet](https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html) and can use any feature it supports. For example, it has a [list of supported tags](https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used). You can personally build the documentation with a newer Java version. See [the 'Checking Javadoc' section](#checking-javadoc) for how to build the documentation locally.
 
 ### Custom tags