Coding conventions

This page contains coding conventions used in the Jacobin code base. Note that many of these conventions grew organically, as needs became clarified. That means that some early code might not strictly follow the conventions. Bringing such code to our attention is a welcome contribution.

variable-name and function prefixes

• cl = class (a Java class)
• err = error
• ex or exc = exception
• f = file. e.g., fname = file name
• fld = field
• fr = frame
• fs = frame stack
• kl = klass (a Jacobin representation of a Java class)
• meth = method

string references in fields

In Jacobin objects, fields are represented as a map inside the object.Object instance. The field entries contain two data items: Ftype, which defines what type of item the field contains, and Fvalue, which contains the actual field data. Ftype is a short string whose possible values are defined in javaTypes.go.

Of note with regard to strings, are these Ftype values:

• types.JavaStringObjectRef is an *object.Object that points to a java.lang.String object
• types.JavaByteArray is the raw string data stored as a slice of Java bytes (that is, int8's)

The above two should be the predominant field types for strings. The following variants are rarely used:

• types.GolangString is a slice of golang bytes (uint8). It should be used only internally to a class and not exposed to the user. Instances of this type should always be converted to Java bytes/Java string objects prior to the user seeing them
• types.ByteArray is the old name for types.JavaByteArray and it should be retired due to its ambiguity

error messages

The convention for error messages is to create them using fmt.Sprintf() and then either return them, return them wrapped in an error, or display them. The string created by fmt. Sprintf is always called errMsg.

gfunctions

The error block returned by gfunctions contains two fields:

• The numeric exception type (e.g. the integer representing IOException) maps to an element in a string table ("java.lang.IOException").
• A descriptive error text (string) that describes the error condition, annotated when possible, with supplied parameter values and/or derived variable values. The gfunction class name, method name, and method type are joined included in the error block information to produce the complete error message.

gfunctions vs. native functions

gfunctions are Java library functions implemented in golang. Native functions are JDK functions written by the JDK team in a native language, generally C++. Native functions are identified in Java by use of the native keyword.

golang vs. go

Wherever reasonable, we use golang to refer to the language, rather than go. This allows us to search the code base for instances of the go keyword more efficiently.