{"id":16374996,"url":"https://github.com/moderocky/stylezie","last_synced_at":"2026-01-27T19:28:20.904Z","repository":{"id":103957401,"uuid":"336505229","full_name":"Moderocky/Stylezie","owner":"Moderocky","description":"The Kenzie Java style guide, organising rules and code conventions.","archived":false,"fork":false,"pushed_at":"2021-12-16T22:04:49.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-02T05:05:30.070Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Moderocky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-06T09:54:02.000Z","updated_at":"2021-12-16T22:04:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"07bcc334-545b-473c-b857-801b155e42dc","html_url":"https://github.com/Moderocky/Stylezie","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Moderocky/Stylezie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FStylezie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FStylezie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FStylezie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FStylezie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Moderocky","download_url":"https://codeload.github.com/Moderocky/Stylezie/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FStylezie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28819336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T18:44:20.126Z","status":"ssl_error","status_checked_at":"2026-01-27T18:44:09.161Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T03:19:02.434Z","updated_at":"2026-01-27T19:28:20.874Z","avatar_url":"https://github.com/Moderocky.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"Stylezie\n=====\n\n### Opus #3\n\nA succinct, consistent and helpful set of Java code conventions, styling guides and general organising rules designed to improve code readability and consistency.\n\nMany existing style conventions are either very old or based on a very old format - some even older than twenty years (and many of the younger Java users!)\n\nWhile the language itself has remained relatively similar, many of the conventions that originally made good sense are no longer relevant due to improvements in either the language itself or to the tools we use for writing it. IDE warnings have reduced the need for explicit nullness, automatic wrapping has reduced the need for set line-lengths, etc. Although we should never assume these technologies are used by everybody (some people still use vim!) it decreases the necessity for such measures.\n\nAs such, this guide aims to provide a more modern and reasonable set of style and code conventions for the discerning programmer. :)\n\n*Written by Kenzie, with some inspiration from [Oracle](https://www.oracle.com/technetwork/java/codeconventions-150003.pdf) and [Google](https://google.github.io/styleguide/javaguide.html) respectively.*\n\n## Preamble\n\nThe importance of code conventions should not be understated.\n\n- Conventions make code consistent, which prevents confusion.\n- Conventions make code faster to read - you can glance at third-party code and understand what something is when conventions are followed.\n- Conventions make code easier to understand - revisiting complex, old code in the future will be painless if the code can be easily interpreted.\n- Conventions help with analysis - if clear and standard rules are followed, errors and feedback will be easier to interpret.\n- Conventions can help with efficiency, both for the programmer and the machine - having a consistent structure can make your work environment faster, and some conventions may have a real impact on runtime efficiency.\n\nThis guide includes:\n\n1. Naming conventions for most elements.\n2. Flow control and usage conventions.\n3. Structuring conventions for larger projects. (TODO)\n4. Testing conventions. (TODO)\n5. Documentation conventions. (TODO)\n\nPlease note that some entries might seem unusual or different from existing and widely-used standards. Most of these differences will be explained (and the purpose clearly stated.)\nHowever, you may not agree with some of them and feel they are in contrast to your own requirements. If this is the case, feel free to pick and choose - as long as you do so consistently. :)\n\n## Common Ideas and Assumptions\n\n1. Assume your code will be used in tandem with lots of other libraries, projects and third-party code. This helps you to work with the idea that you need to share resources with other things. It also means you should avoid the global state, and any common namespaces not related to your project that might conflict with others.\n\n2. Names should reflect purpose. In almost every case, the name of an element should clearly refer to what it does. This helps to improve readability.\n\n3. Always use the narrowest scope. For access modifiers and modules, you should only expose things as much as they need to be. Exposing unnecessary things can pollute documentation and confuse a user, and may also put your program at risk if an unsafe internal method is exposed.\n\n4. Keep initialism consistent. If a name should be in `lowerCamelCase`, use `xml` rather than `xML`. If a name should be in `UpperCamelCase`, use `HTML` rather than `Html`. Avoid uncommon abbreviations unless obvious or necessary.\n   \n5. Code should be keyword-centric. New lines will almost always start with either an action keyword or, where none is appropriate, a type. This rule helps to keep code purpose-oriented and avoids unnecessary or unclear line-breaks.\n\n## 1. Naming Conventions\n\n### Module Names\n\nModules were introduced in Java 9 as a simple way to control access and organise a large project.\n\nAn introduction can be found [here](https://www.oracle.com/corporate/features/understanding-java-9-modules.html).\n\nA module should have a clear and singular purpose. It must be defined in a file named `module-info.java`.\n\nModules should be used consistently - if a project uses modules, it should be entirely modular.\n\nModule names are similar to package names. They should be written in lowercase, separated by `.` and follow the\ntraditional reversed-domain style. Module names should start with and use a domain owned by the creator, or one in\ndirect reference to the project.\n\nExamples:\n\n- I own `kenzie.mx`, I may safely use `mx.kenzie.something`\n- I do not own `kenzie.me`, therefore I should not use `me.kenzie`\n- `project.thing` is not a valid domain, therefore I should not use it.\n\nAfter the initial reversed domain, the module name should contain the project name, and also offer an indication of what\nis contained in it.\n\nGood examples include:\n\n- `mx.kenzie.myproject.http` (for a project named myproject, and a module about http connections)\n- `mx.kenzie.myproject.sockets` (for a project named myproject, and a module about sockets)\n\nBad examples include:\n\n- `mx.kenzie` (this is just a domain, it tells me nothing about the project or the module, and will conflict if I\n  re-used this name)\n- `mx.kenzie.sockets` (this tells me about the module, but not about the project it's in)\n- `sockets` (this is just a word, it doesn't tell me where the module comes from or who made it - if I get an error from\n  a third-party library's module, I need to know how to find it!)\n\n### Module Entries\n\nThe entries in the `module-info.java` descriptor should be clear and consistent.\n\nThere are no specific necessities to the orders of your entries, but these should be grouped by type for clarity and to\navoid confusion. It is generally practical to put the requirements first.\n\nEntries that have multiple comma-separated values should have the values placed on their own lines. Module and package\nnames can be quite long, and this will help to keep it organised.\n\nThis should be kept on one line, as it is short and clear:\n```opens org.example.one to org.example.two;```\n\nThis should be split over multiple lines, as it may otherwise run past the line length:\n\n```\nopens org.example.one to\n    org.example.two,\n    org.example.three,\n    org.example.four;\n```\n\nA larger example can be seen below:\n\n```java\nmodule org.example.project.thing {\n   requires java.base;\n   requires java.net.http;\n   requires static java.se;\n   requires transitive java.instrument;\n   requires transitive java.desktop;\n   opens org.example.something;\n   opens org.example.one to org.example.two;\n   opens org.example.one to\n           org.example.two,\n           org.example.three,\n           org.example.four;\n}\n\n```\n\n### Package Names\n\n1. Package names should be written in lowercase, separated by `.` and follow the traditional reversed-domain style,\n   using alphanumeric characters (see caveat). This is done for the sake of consistency and has been standard since\n   Java's inception.\n2. Package names should start with and use a domain owned by the creator, or one in direct reference to the project.\n   This is partly as a way to help identify the creator or source of code, and partly for consistency. Your code is your\n   responsibility - to an extent. If somebody finds an error in a compiled, third-party library and wants to report it\n   to the creator, this provides an easy way for them to contact the creator. In some cases, a reversed email or\n   sub-domain may be more appropriate to use as a package starter.\n3. Package names should include a reference to the project. This allows you to avoid conflicts with your other projects,\n   and makes it clear where the library comes from.\n\nGood examples:\n\n- `mx.kenzie.myproject.sockets` - This is a domain I own, it references my project name (myproject), and the package is\n  a clear indication of its purpose (sockets)\n\nBad examples:\n\n- `project.thing` is not a valid domain, therefore I should not use it.\n- `org.my-domain.myproject` contains an illegal character.\n- `org.example.myProject` has incorrect casing.\n\nCaveat: If your domain contains a character that is illegal in a package name (such as `-`) this is the only time when\nan alternative may be used.\n\nFor example, the domain `ab-cd.com` could not be used as a package name. While `com.abcd` would be a sensible\nalternative, this might cause confusion (especially if the result domain is in-use or removal of the hyphen affects\nreadability or changes the meaning.) As a result, the `_` underscore character may be used as a replacement.\n\nNote that this is a deviation from the original Java style guide. I believe that the result (improving readability and\navoiding the potential conflict) justifies its use.\n\n*Justification:*\nNot only do unique package names prevent any unexpected conflicts, they also provide some identification as to the producer or the purpose of the application. Shaded code, such as third-party libraries without clear manifests or POM files, may be difficult to find the creator or source of. The package name will give an indication of the creator's github, or the owning corporation's domain name. This makes it easier for a potential user of a library to report bugs or find documentation.\n\n### File Names\n\nAll Java code-containing files should have their names formatted in `UpperCamelCase`. This includes classes, interfaces,\nannotations and records. Class files should share the name of either the public class, or the most important class\ninside them.\n\nThe only exceptions to this rule are `package-info.java` and `module-info.java` which require those specific names.\n\n*Justification:*\nThis is a requisite for public classes, and should be propagated to non-public code files for the sake of consistency.\n\n### Class Names\n\nClass names should not regularly exceed a length of 24 characters. This number does not include type parameters, file\nextensions or extraneous parts.\n\nClass names should start with a letter, and contain only alphanumeric characters.\n\nClass names should be at least three characters, and should avoid acronyms unless very common (see XML, HTML, etc.)\n\nClass names should rarely be identical to that of a public JDK class (e.g. you shouldn't name a class `Integer`)\nexcept when the word is in very common use (e.g. `List` or `Remote`) or the JDK class is incredibly obscure\n(e.g. `UnsafeFieldAccessorFactory`.)\n\nClass names should be succinct and should describe the purpose of a class (see common assumptions.)\n\nInternal interface names may be preceded by an uppercase `I` for clarity. This is especially useful when abstracting an\nexisting class to an interface layer. This should be done only for internal use or to avoid conflicts.\n\nAbstract class names may be preceded by `Abstract` for the same reasons as above.\n\nWhen using procedurally-generated classes (such as via bytecode-generating libraries) the class name should be prefixed with the special character `$` to differentiate it from regular classes.\n\nPrefixes should be avoided for any other case.\n\nGood examples:\n\n- `SocketServer` Not a JDK class, describes its purpose, short and succinct.\n- `ByteVector` Not a public JDK class, describes its purpose, not too long.\n- `StringSorter` Clear, does what it says on the tin.\n- `HTTPServerManager` Clear, expressive, not too long.\n\nBad examples:\n\n- `Integer` A very common JDK class.\n- `stringSorter` Incorrect casing.\n- `ByteVector_` Contains a non-alphanumeric character.\n- `Bytevector` Incorrect casing.\n- `AlphabeticAndNumericStringSorter` Overly lengthy, clumsy.\n- `X` Too short, not descriptive.\n- `PQ24AJC` Has no bearing on the contents.\n\n\n*Justification:*\nBy using this consistent naming style for class names, it becomes much easier to identify the use of class names in raw code. The use of `UpperCamelCase` helps to differentiate between words in the name, while making it shorter than the equivalent divider in `snake_case`. This is also a very common naming style and there is no good reason for deviating from it. Avoiding sharing the name of JDK classes will help to prevent confusion when seeing unqualified class names in raw code. It can also prevent qualifying problems for classes in the `java.lang` package.\n\n### Field Names\n\nField names should be at most 24 characters.\n\nStatic field names should describe the purpose of the stored object.\n\nDynamic field names should either describe the purpose of the stored object, or be named after its type.\n\nFields can be split into distinct groups. As these groups behave differently, it is helpful to use different code conventions for them.\n\n#### Static Constants\n\nA constant is a value that cannot be changed during a program's runtime. In Java, these are denoted with the `static` and `final` keywords.\nThese values are assigned when the class is loaded, and should never change after that point.\n\n'True' constants are `static final` primitive fields that go into the constant pool. These values cannot be altered by any means once they have been assigned.\n\n'Effective' constants are `static final` fields of any object type. These values should never change during normal program execution, **however** it is possible to alter them using unsafe reflection.\n\nAll `static final` fields should be named in `UPPER_SNAKE_CASE`.\n\n#### Static Fields\n\nNon-final static fields should be named in `lowerCamelCase`.\n\n#### Dynamic Fields\n\nDynamic fields should always be named in `lowerCamelCase`. This is irrespective of any other modifiers.\nDynamic constants should still be named in `lowerCamelCase`, despite being in the constant pool.\n\n*Justification:*\nDespite being in the constant pool, dynamic constants are only accessible via an instance and are, for almost all intents and purposes, simply final fields.\n\n### Enum Names\n\nJava 'enums' are effective constants with special additional properties.\n\nThey should be named as constants are, in `UPPER_SNAKE_CASE`.\n\n### Method Names\n\nMethod names should always be named in `lowerCamelCase`, starting with a letter.\nMethod names should not exceed 24 characters.\nMethod names should describe their purpose accurately and succinctly.\n\nMethods that access a private field should be prefixed with `get` and `set` accordingly. Methods that access a boolean should be prefixed with `is`.\n\nThe `$` and `_` character are available, but are traditionally reserved for Java's internal use.\nThe `$` character may be used in auto-generated methods internal to a library.\n\nMethods for internal reflection should be prefixed with `reflected$` (for use with ReflectionFactory.)\n\nPrivate methods for internal use may be suffixed with a `0` if a public method with the same name exists.\nAn example can be seen below:\n```java \npublic void myMethod() {\n    // perform security access check here\n    this.myMethod0(); // call internal version\n}\n\nprivate void myMethod0() {\n   // internal behaviour\n}\n```\n\nSo-called 'getter' methods from a record should not be preceded by `get...` as these are effectively constant references\nto (supposedly) immutable fields.\n\nGood method names:\n- `sortStrings` Clear name and purpose.\n- `getAge` Clear name, clear get-behaviour.\n- `destroy` Clear name and purpose.\n- `setBehaviour` Clear name and purpose.\n\nBad method names:\n- `i1054c` Random, obfuscated, no clue as to what it does.\n- `SetName` Improper casing.\n- `a` Too short.\n- `setTimeAndDateOfTimestamp` Too verbose, could be more succinct.\n- `set` No indication of what is being set, could be more descriptive.\n\n### Local Variable Names\n\nLocal variables should be named in `lowerCamelCase` and avoid numeric characters where possible. The name should describe either the type of the variable or the purpose.\n\nVariable names should be at most 16 characters. Single-character variable names should be avoided unless directly relevant, such as naming grid coordinates `x` and `y`.\n\nGood variable names:\n- `final String name` Variable purpose is clear and type can be assumed.\n- `final String string` Variable type is clear.\n- `final Object handle` Variable purpose is clear, name is short and succinct.\n- `final int age` Variable purpose is clear at use, and type can be assumed.\n  \nBad variable names:\n- `final String s` Name is too short and unclear.\n- `final Method m1` Nothing can be assumed from the variable name. Easy to confuse.\n- `final String obj` Name does not relate to variable type or purpose.\n\n\n*Justification:*\nVariables with clear names make code more legible and make it easier to understand what is going on by looking at any point of the code. If the purpose and the type of the variable can be assumed just by reading the name then this makes improving or working with the code a lot easier. \n\nThe exception to this rule is for primitive variables in very short methods where the variable type is immediately clear at use. The single-letter names correspond to the type descriptors for primitives.\nNote: this does not mean single-letter names have to be used - by all means pick a name that describes the purpose of the variable, though in many very short methods this is cumbersome and unnecessary.\n\n|Type|Label|\n|----|-----|\n|boolean|`z`|\n|char|`c`|\n|byte|`b`|\n|short|`s`|\n|int|`i`|\n|long|`j`|\n|float|`f`|\n|double|`d`|\n\n### Parameter Names\n\nMethod parameters should be named as variables are, following the same rules. However, the convention of describing the parameter's purpose is much more important here, as the parameter name will be the only clue to the input's purpose outside any documentation provided.\n\nGood parameter names:\n- `final String name` Parameter purpose is clear and type can be assumed.\n- `final int age` Parameter purpose is clear to method user.\n  \nBad parameter names:\n- `final String string` Parameter purpose may be unclear unless it can be inferred from the method name.\n- `final int var` Parameter purpose is unclear to user, and type is unclear when used in code.\n\n\n*Justification:*\nAll of the justification for variable names applies here. As well as this, parameter names are somewhat front-facing and provide a very basic level of documentation for using your method, so they ought to be clear to the user. \n\n### Block Label Names\n\nLabels for conditions, loops and blocks should be named to give some clue as to the section's purpose.\nThey should be written in `lower_snake_case` to be immediately differentiable from method, variable or field names and to make sure they are legible and clear to the user. Numbers should be avoided.\n\nImplicit labels that apply to a single thing (such as a loop) do not require braces if placed properly.\nSee structural conventions for more details.\n\nBlocks should very rarely have no label applied unless used for necessary flow-control rather than organisation.\n\nGood label names:\n- `loop_citizens: // for...` Describes the purpose of this section clearly.\n- `check_valid: //...` Describes the purpose, if a `break` instruction is used the exit is clear.\n- `prepare_exceptions: //...` Describes the purpose, easy to break from.\n\nBad label names:\n- `label: //...` Provides no information.\n- `x: //...` Name is too short. Provides no details.\n- `block12: //...` Confusing. The break instruction could be unclear to the reader.\n\n\n*Justification:*\nLabels are very different from all other members in that they affect the body structure rather than providing any storage or execution function. Having a different naming convention helps to make their difference clear, as well as being slightly more legible than the typical `camelCase` that Java uses.\n\n### Type Parameter Names\n\nType parameters are found in generic classes and methods. Their names should be written in `UpperCamelCase`, similar to class names.\nA type parameter should not have the same name as a class if that class is used (or has a chance to be used) within the scope of that parameter. Hence, naming a type parameter `Type` is only acceptable if the `java.lang.reflect.Type` interface would never be used within its scope.\nType parameter names should describe their purpose.\n\nThis breaks from Oracle's original [type parameter conventions](https://docs.oracle.com/javase/tutorial/java/generics/types.html).\n\n**Justification:**\nOracle advocated for single-letter (`T`, `K`, `V`, etc.) type parameter names in order to differentiate them from classes or other elements. They felt this was, at the time, necessary due to the rudimentary nature of IDEs and potentially making it unclear. Later style guides have revised this to allow names beginning with certain prefixes or suffixes (`TValue`, `ValueType`, etc.) for the same reasons.\nRespectfully, I no longer feel this is necessary, if it ever was. Type parameters are not classes, but they are stand-in descriptors of them. If the type parameter is declared in the header then I feel it is no different from importing a class rather than using the fully-qualified name. IDE technology has improved significantly, so the differentiation is no longer such an issue. \n\nGood type parameter names:\n- `DataRecord` Name and purpose are clear.\n- `ObjectType` Name and purpose should be clear in use case.\n- `InputType` Suitable for a type parameter that overloads a method's input type.\n- `Value` Suitable for a generic class like map where value type is generic.\n\nBad type parameter names:\n- `T` Tells the reader nothing about it.\n- `Object` Hides a very common Java class.\n- `String` Hides a very common Java class.\n- `TValue` Unnecessary prefix.\n- `T1` Cryptic and unhelpful.\n\n\n## 2. Usage and Flow Structure Conventions\n\n### Class Layout\n\nThe order of entries in a class should follow a consistent schema and make use of line-breaks to separate members clearly.\n\n#### Package Definition\n\nThe package definition should be the first entry in the file. A line break should follow before any further entries.\n```java\npackage com.example;\n\npublic class Alice {\n    \n}\n```\n\n#### Imports\n\nIf imports are used, these should go between the package and the leading class declaration, with line breaks to separate the sections.\n\n```java\npackage com.example;\n\nimport java.util.Arrays;\nimport java.util.List;\n\npublic class Alice {\n\n}\n```\n\nIf five or more classes from the same package are to be imported, a wildcard `*` import should be used to reduce the unnecessary file size.\n\n```java\npackage com.example;\n\nimport java.io.InputStream;\nimport java.util.*;\n\npublic class Alice {\n    \n}\n```\n\n#### Type-level Annotations\n\nType-level annotations should be placed on the line preceding the class declaration. Type-level annotations should **not** be placed after the modifier when declaring a class. This is to increase clarity.\n\n```java\npackage com.example;\n\n@Deprecated\npublic class Alice {\n    \n}\n```\n\n#### Inheritance\n\nSingular extensions and implementations should be placed on the same line as the class declaration.\n\n```java\npublic class Alice extends Bob implements Person {\n    \n}\n```\n\nIf multiple or uncharacteristically long interfaces are required, these may be placed on a separate line if it makes the class declaration easier to read (such as to prevent it running past the line length.)\nAny line-breaks should always be placed before a keyword, to make sure that the purpose of the following value is clear.\n\n```java\npublic class Alice \n    extends Bob \n    implements Person, Employee, Graduate, Thing {\n    \n}\n```\n\n#### Generic Classes\n\nIf a generic class has simple or unbounded type parameters these should be placed on the same line as the declaration.\nSee the section on naming conventions for more information about type parameters.\n\n```java\npublic class Box\u003cContents extends Valuable\u003e {\n    \n}\n```\n\nIf a generic class has multiple type parameters, and the declaration header becomes too long to be easily legible, line-breaks should be used to separate these.\nLine-breaks should be placed after the opening diamond `\u003c` and after every comma.\nThere should not be a line-break before the closing diamond `\u003e`.\n\n```java\npublic class Box\u003c\n    Material extends Waterproof \u0026 Durable,\n    Contents extends Valuable \u0026 Heavy \u0026 Dangerous\u003e {\n\n}\n```\n\n### Order of Class Members\n\nClass members should be ordered in a consistent hierarchy, according to the following rules. These rules should be applied in the given order (e.g. the member type trumps the member visibility.)\n\n#### Type\n1. Fields\n2. Constructors\n3. Methods\n4. Classes\n\n#### Belonging\n1. Static (belonging to class object)\n2. Dynamic (belonging to instance)\n\n#### Visibility\n1. Public\n2. Package-private\n3. Protected\n4. Private\n\nBy applying these rules, the ordering of members should be clear.\nA very rudimentary example of correct ordering is shown below.\n\n```java\npublic class Box {\n    \n    public static final int NUMBER = 0;\n    \n    public int first;\n    private int second;\n    \n    public Box(int size) {}\n    \n    Box() {}\n    \n    public static void myMethod() {}\n    \n    public void test() {}\n    \n    static class Tree {}\n    \n    class Leaf {}\n\n}\n```\n\n### Field Layout\n\nEach field should be defined on its own line with the narrowest appropriate access modifiers.\n\n```java \nprivate String name;\nprivate int age;\n```\n\nThe exception to this rule is when declaring multiple fields in one statement. While this is permitted, it is rarely appropriate except for data-oriented classes.\n\n```java \nprivate String name, surname;\nprivate int length, width, height;\n```\n\nIf an excessive number of declarations is done in the same statement, these may be placed on multiple lines. The following declarations should be indented for clarity.\n\n```java \nprivate int first,\n    second,\n    third,\n    fourth,\n    fifth;\n```\n\n#### Field Annotations\n\nBasic annotations that are augmenting the field itself should be placed above the declaration statement and not after the modifier.\n\n```java \n@Deprecated\nprivate int number;\n```\n\nAnnotations that are designed to apply to the field's value specifically (such as nullness information) should instead be placed after the modifiers and before the type.\n\n```java \n@Deprecated\nprivate @NotNull String name;\n```\n\n**Justification:** Having two places to attach field-target annotations makes it clearer what the annotation is in reference to: the field or its contents specifically. While all field-target annotations are technically targeted to the field itself, many of the most common are in fact in direct reference to the object stored in it. This makes that distinction clear.\n\n\n#### Field Assignment\n\nIf fields can have a common value, this should be assigned in the declaration, rather than the initialiser block or the constructor.\n\n```java \npublic int number = 1;\n```\n\nThis is especially true for final fields, since assigning them during the declaration allows their value to go into the constant pool if they are of a primitive or special type.\n\n```java \npublic final int a = 1; // Constant in the pool.\npublic final int b; // Final but not constant.\n\n{\n    b = 2;\n}\n```\n\nDynamic constants do not need to be made static (as some other guides suggest) since the value is in the constant pool, so there is no real resource benefit (other than a few bytes saved in memory.)\n\n\n### Method Layout\n\nEach method should be declared on its own line with the narrowest appropriate access modifiers. Methods should not be declared final unless doing so is necessary. This is in contrast to all other finality rules, as method finality restricts inheritance and so should generally be avoided.\n\nMethods do not need an ending semicolon `;` and the method body brackets should open on the same line as the declaration.\n\n```java \npublic void myMethod() {\n    // Body code.\n}\n```\n\n#### Annotations\n\nMethod annotations should be used in one of two ways, depending on which is appropriate to the situation.\nAnnotations that are designed to describe the method itself (such as deprecation warnings, tests, target for JIT, flags for reflection, etc.) should be placed on the preceding line.\n\n```java \n@Test\n@Deprecated\n@SuppressWarnings(\"all\")\npublic void myMethod() {\n    // Body code.\n}\n```\n\nAnnotations that are designed to apply to the method's return value (such as nullness information) should instead be placed after the modifiers and before the return type.\n\n```java \npublic @NotNull String myMethod() {\n    // Body code.\n}\n```\n\nIf the annotations of the second kind are cumbersome or unusually long, a line-break is allowed here.\n```java \n@Deprecated\npublic static @NotNull @Finalised @ConstantReturn\nObject myMethod() {\n    // Body code.\n}\n```\n\n**Justification:** Having two places to attach method-target annotations makes it clearer what the annotation is in reference to: the method or its result specifically. While all method-target annotations are technically targeted to the method itself, many of the most common are in fact in direct reference to the result. This makes that distinction clear.\n\n#### Generic Methods\n\nIf a generic method has simple or unbounded type parameters these should be placed on the same line as the declaration.\nSee the section on naming conventions for more information about type parameters.\n\n```java \npublic \u003cAccessPoint\u003e void myMethod() {\n    // Code body.\n}\n```\n\nIf the type parameter declaration is long, a line-break can be placed after the header before the method return type to improve readability.\n\n```java \npublic \u003cClassMember extends Member \u0026 AnnotatedElement\u003e\nvoid myMethod() {\n    // Code body.\n}\n```\n\nIf a generic method has multiple type parameters, and the declaration header becomes too long to be easily legible, line-breaks should be used to separate these.\nLine-breaks should be placed after the opening diamond `\u003c` and after every comma.\nThere should not be a line-break before the closing diamond `\u003e`.\n\n```java \npublic final \u003c\n    ClassMember extends Member \u0026 AnnotatedElement,\n    Material extends Waterproof \u0026 Durable,\n    Contents extends Valuable \u0026 Heavy \u0026 Dangerous\u003e\nvoid myMethod() {\n    // Code body.\n}\n```\n\n**Justification:** Clear and neat formatting makes the code faster to read, especially in narrower windows, and makes the type parameter declaration clearer to the reader.\n\n### Brace Arrangement Rules\n\nThe opening `{` bracket should always be placed after a space (and its opening action.)\nOpening braces should never have a line-break before them.\n\nThere are **no** exceptions to this rule.\n\n\n#### Double-Brace Initialisers\n\nThe practice of altering an object at initialisation using a \"double-brace initialiser\" should be **avoided**.\n\n(Example for reference.)\n```java \nnew ArrayList\u003c\u003e() {{\n    add(\"hello\");\n    add(\"there\");\n}};\n```\nIt is often used as a time-saving gimmick or to avoid dedicating lines in a constructor to filling a list or map field. While it may appear useful on the surface, it has two unintended consequences.\n\nFirstly, whenever this is used it implicitly creates an extending class. Creating additional classes for no purpose should generally be avoided. \nSecondly, because it is an extending class, the class is functionally nonidentical to the original class, which can cause unintended issues in equality checks. \n\n\n#### If or Switch\n\nSwitch statements should be preferred over an if/else branch under the following circumstances:\n- Your switch statement would have more than three cases.\n- A switch statement is applicable to the type.\n- The cases can be properly applied to a switch statement.\n\nThis is especially true if your switch statement can be fully enclosed (for enums, etc.)\n\n```java \nswitch (ordinal) {\n    case FIRST:\n    case SECOND:\n    case THIRD:\n}\n```\n\nHowever, it should be noted that switch statements produce a lot more 'compiler garbage' than simple if/else checks, though this is rarely a major concern.\n\n**Justification:**\nIf `javac` can compile your switch to a `tableswitch` then it may become faster to use as not all of the cases need to be evaluated, as they would in an if/else equality check.\nEven a `lookupswitch` could be faster, since the lookup conversion will be more efficient with a large number of cases.\n\n\n#### Labels and Blocks\n\nBlocks have always been an underused feature of Java. They allow for more delicate and precise flow-control (leading to much shorter and more efficient code in complex loops and conditionals) as well as providing a way to keep code ordered without resorting to comments and extrinsic metadata.\n\nBlocks should always have a preceding label, unless they have a functional clause before them.\n\nFunctional clauses:\n- `do`\n- `while ()`\n- `if ()`\n- `else`\n- `for ()`\n- `synchronized ()`\n\nExamples:\n```java \nwhile (true) {\n    // 'while' clause serves as label.\n}\n\ndo {\n    // 'do' clause serves as label.\n}\n    \nif (true) {\n    // 'if' clause serves as label.\n}\n\nlabel: {\n    // No preceding clause, needs a label.\n}\n```\n\nLabels may also be used as a way to organise or demarcate code. You may, for example, label a conditional or loop clause in order to keep note of its type. This is also wise in nested loops as it allows you to target which to continue or break from.\n\nA very rudimentary of targeted labelling is shown below. By placing the labels before the loop clauses they may be used as targets for the `continue` and `break` instructions.\n```java \ncount_up: for (int i = 0; i \u003c 10; i++) {\n    if (object == null)\n        continue count_up;\n    count_down: for (int i1 = 10; i1 \u003e 0; i1--) {\n        if (object.getClass() == type)\n            break count_up;\n        else if (thing.getClass() == type)\n            break count_down;\n        continue count_down;\n    }\n}\n```\n\n**Justification:** Effective use of blocks and labels can increase the readability of code - particularly complex or cryptic code - massively, as well as keeping it more organised and allowing the recycling of variable names.\nOn top of this, `javac` strips out any unnecessary labels or blocks while compiling, meaning there is no real disadvantage to \"over-labelling\" code.\n\n\n### Variable and Parameter Finality\n\nAccording to rule #3, finality should be used in every appropriate place. This includes using the `final` modifier on method parameters and local variables.\n\nIn short methods (under five lines) or in the cases where variables have only one or two uses the finality can be ignored.\n\nIn longer methods, or where a variable or parameter is used many times, the variable should be made final.\nObviously, some variables cannot be made final, especially ones that undergo loop reassignment.\n\n**Justification:**\nMost users are under the impression that `final` variables have no additional value. However, this is not the case.\nPrimitives and simple types will be pulled from the constant pool rather than loaded from the local variable pool. On top of this, making variables final can allow for faster and better optimisation by the JIT compiler (detailed in Simmons Jr.'s 'Hardcore Java' Ch.2) and has the added benefit of preventing 'operator errors' such as accidentally reassigning a variable.\n\n\n## 3. Project Structure Conventions\n\nTODO.\n\n## 4. Testing Conventions\n\nTODO.\n\n## 5. Documentation Conventions\n\nTODO.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoderocky%2Fstylezie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoderocky%2Fstylezie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoderocky%2Fstylezie/lists"}