Info

This page contains additional info, specifically FAQs, versioning information, or source code organization.

Project Versioning

SNAPSHOT archives on Black Rook contain the date it was compiled/released in the form of YYYY.MM.DD.HHMMSSCCC (year, month, day, hour, minute, second, millisecond). RELEASES are made up of the following version numbers.

Black Rook projects are versioned in this fashion:

[major].[minor].[subminor]

The [major] number describes a major version number. A change in this number from one version to the next is for HUGE changes in a project, such as API refactoring, reorganization, changes in API behavior, or "program breaking" changes. Ostensibly, one should gather that this version will be COMPLETELY INCOMPATIBLE with programs and tools that use the previous major number.

The [minor] number describes a change or addition in features to a project. A change in this number from one version to the next is for small changes in a project, such as package/class/method/field additions, code deprecations, and some fixes. Changes here can be program breaking, but only rarely.

The [subminor] number describes small to minute changes in a project, usually leaving API structure completely the same as the previous version, except something was fixed or changed internally (nothing End-Users of a library should worry about). It could also mean slight changes to uncompiled source, such as comments, license info, or documentation.

The version numbers are not to be taken as decimal-equivalent. A version number of 1.10.0 is NOT the same as version 1.1.0 (1.10.0 is a more recent version).

Questions about library version compatibility should go to Support.

Coding Practices

Black Rook uses the following coding standards for its source code - the below notes should help you better navigate the source and make changes to it, keeping its current motif (be forewarned that there may be parts of the code that do not adhere to these rules strictly, such as older code that has not been touched in a while. Rest assured it will be remedied soon).

  • All packages reside in the com.blackrook package tree.
  • As with Sun's accepted Java coding standard, all classes and interfaces are UpperCamelCase.
  • As with Sun's accepted Java coding standard, all references, fields, and methods are lowerCamelCase.
  • Fields/methods/identifiers and classes that start with acronyms keep the same case as the beginning character ("UDMFReader", NOT "UdmfReader". As an additional example, "urlClassLoader", NOT "urlclassLoader" NOR "uRLClassLoader").
  • All code is indented with HARD tabs. Comments that line up in an organizational or pictographic manner are aligned with spaces. HTML is used in Javadoc comments.
  • As with Sun's accepted Java coding standard, all interfaces that work with Sun's "event" model of coding are suffixed with "Listener".
  • As with Sun's accepted Java coding standard, all classes that work with Sun's "event" model of coding that are "barebone" implementations of "Listeners" are suffixed with "Adapter".
  • Field value retrieval/setting methods for use outside of the originating class are prefixed with "get"/"set", respectively.
  • Methods that "guess" or estimate contents of data or structures or make attempts to classify seemingly unorganized data are prefixed with "intuit".
  • Methods that explicitly create new data from existing data or structures are prefixed with "gen".
  • Methods that return the cardinality of a list or group of objects are suffixed with "Count" or prefixed with "getNum". "Count" is preferred, and "getNum" is currently being phased out.
  • Most files created for Black Rook are CRLF-terminated, that is, all new lines are designated with Carriage Return followed by a Line Feed character (Windows/DOS/VMS style). Be mindful of this when you open the source files for viewing (most text editors or IDEs these days can detect this, though).
  • Variables, fields, classes, interfaces, and method names should be as descriptive as humanly possible (we live in the age of auto-completion and compiled code - no more excuses for short or ambiguous names). The exception to this rule are temporary variables (such as variables in while/for loops).

The generalized rule is: If it helps with universal code readability, do it!

Curly Brace Use

In the code, curly brace use is as follows:

For if/while/for/method (and most other statement) blocks, the first brace starts on the next line aligned with the declaration, and the last is on its own line as well, lined up with the beginning brace.

public void doesSomething()
{
    // code goes here...
    if (expression)
    {
        // code goes here....
    }
}

Statement blocks that consist of ONE statement in its body do not have braces, and are on the next line, indented. This may not be the case however, if braces assist in readability.

if (x < 5)
    x = 5;

For do-while blocks, however, put the opening brace with the do, same line, and the closing with the while, beginning of the line.

do {
    // a bunch of stuff.
} while (x < 4);

For try-catch-finally blocks, it gets a little weird. I'll let the code examples describe them:

/** Single catch, no "finally". */
try {
    FileInputStream fis = new FileInputStream(new File("blah.txt"));
    fis.close();
} catch (IOException e) {
    // Handle exception.
}
/** Multiple catch, no "finally". */
try {
    FileInputStream fis = new FileInputStream(new File("blah.txt"));
    fis.close();
} catch (FileNotFoundException e) {
    // Handle exception.
} catch (IOException e) {
    // Handle exception.
}
/** Multiple catch, with "finally". */
try {
    FileInputStream fis = new FileInputStream(new File("blah.txt"));
    fis.close();
} catch (FileNotFoundException e) {
    // Handle exception.
} catch (IOException e) {
    // Handle exception.
} finally {
    // Finally code here.
}
Anonymous classes may not follow these conventions, following instead what would make code less unsightly.