CONVENTIONS.md

Documentation | 文

This markdown document provides a simple overview of how things go around regarding usage & readability of source code (not this repo!).

File Naming

File Naming, source suffixing, represents how most Java Source Files are named based on their intended purposes / category.

JAVA Source Files

Formatting Most if not all Java Source Files provided do not align directly with the standard Java Coding Standards/Conventions. Instead archaic formatting from other common languages are used. This is because some common Java Standards make the code much more verbose and harder to understand/read at an instant. This specific format is not perfect and is designed for quick and specific attributes to stand out and thus be easier to debug.

1. Indentation Style "Allman": Using the Allman indentation style with opening { braces on a new line.

public class Test_IO
{
  public static native void print(String... e);
}

2. Type Attributes extends,implements -> class,interface,abstract class Attributes are presented in a vertical list like manner for easy readability.
   

public class HelloMe
    extends
    World
    implements
    Runnable,
    Comparable<Integer>,
    Serializable
{

}

3. Snake Case, Pascal Case, Camel Case Most Java source files use method names with snake casing with some camel casing for methods are to be used for outside of the standard Halcyon environment.

4. Type & Importance expression For generics and other specific type definitions, spacing is required and other important expressions are separated to make them stand out.

Halcyon.java$__LINK__(): (Underscores before and after to indicate a very important method to call)

public static void __LINK__()
{
  /*...*/
}

Average Generics:

List< AtomicInteger > e = new ArrayList< >();
//   ^^^^^^^^^^^^^^^
// Types here are spaced out from the brackets for better readability

File Name Prefixing

Prefix	Description
gui_	Represents standalone GUI Components that depend on dgui_ components to make a whole usable component. Also known as the boilerplate GUI Component
dgui_	Represents dependent GUI Components that require itself to be added to a gui_ based component for it to work
use_	Defines general functionality; functionalities could either be all static or a usuable class defining an instance for functionality. Generally known as a usable. Note: If all usability functions are declared as static, this usable known as a "boilerplate usable"
const_	Defines constants, most often encountered as an interface. Should not define a constructor & functions (unless for additionally functionality to the constants)
sys_	A use_ variation that clearly specifies that this class defines and/or uses functionality that are defined with native
NONE	When no prefix is encountered, it should be noted as a "Runner" class meaning it most likely defines a public static void main OR it could be a use_ (or variations of it) that is used commonly: saves time typing
impl_	Defines a abstraction of abstract class OR abstract interface where certain functionality is abstracted and to be implemented.
evnt_	A impl_ variation that clearly specifies that this abstraction is used for event handling, specifically for event callbacks
has_	Defines a marker annotation that can be used with code.

For child classes like the class use_Struct.java, which defines usable data structures, all child classes start with the class name (excluding prefix & underscore), so an existing child class would be struct_Pair or struct_Trio under use_Struct.

SCRIPT Files

Prefix	Description
run_	Represents the entirety of most RUNNABLE script files, like BASH, POWERSHELL, etc.. Runnable meaning it is intended to be executed via a Shell by the user. Runnables are usually meant to be source files and not compiled

Locale Resource Files

Prefix	Description
HalcyonLang_	A Halcyon Language Locale file. This prefix is most likely followed by the language code (e.g. "en_US")