Jailbreak Developer Network: Guidelines

The following Guidelines specify formal design criteria in order to provide end users and content creators with a consistent, neat, easy-to-use and easy-to-understand interface to Jailbreak.

Map Guidelines

Unless good design reasons speak against it, Jailbreak 200x maps must meet the following requirements:

• Have the DefaultGameType set to Jailbreak.Jailbreak.
• Have an Arena.
• Have a scoreboard minimap.
• Use JBGameObjectiveSwitch for the release switches.
• Have a custom execution sequence, possibly using JBExecution actors.
• Have JBCamera viewpoints and/or JBScreenMap screens in the jails.
• Have the ObjectiveName property of their GameObjectives set to an empty string (or a short string if there are several switches per team).
• Must not be dependent on UT2003 Bonus Pack content.

UT2003 compatibility is preferred, but not required if a map makes good use of resources which are only available in UT2004.

Code Guidelines

General

Language: English

Since this project has an international audience, code, comments and documentation are exclusively in English.

Localization

Everything the end user can come in contact with must be localizable. That includes screen output and spoken audio.

No Tabs!

There is no global consensus on how many character widths a tab character represents (Epic uses four character widths, most text editors eight character widths), and if tab widths can vary from user to user, this makes decent horizontal source line formatting unportable. Every decent text editor suitable for coding allows on-the-fly replacement of tabs by space characters.

Class Names

Class names should be self-explanatory. Probably more important than that is that they aren't misleading by being too generic or poorly chosen. A "sequence," for instance, can be anything; if you're referring to a death sequence, you might do better calling it an "execution."

Prefix

All Jailbreak classes start with JB (with the notable sole exception of class Jailbreak), directly followed by the rest of the class name. – Jailbreak thus creates its own namespace and makes it easy for users to directly recognize a class as belonging to Jailbreak.

Characters and Capitalization

Class names don't contain any characters except upper- and lowercase letters. If a class name consists of multiple words, they are individually capitalized and then concatenated. The first letter after the prefix is an uppercase letter.

Grouping

Multiple classes belonging to the same feature group (like all classes belonging to bot support) share a common class name prefix (like JBBot... for all classes related to bot support). – This automatically groups classes and class source files next to each other in alphabetical listings. This tends to result in "reversed inheritance", eg JBBotSpecial is a subclass of JBBot.

Commenting

If the code and the comments disagree, then both are probably wrong. – Norm Schryer

Comments and comment headers give source code a visual structure and make it much more convenient to browse and understand code, both your own and other people's. Being able to recall a function's purpose by reading a function comment header saves more time in the end than it takes to write it in the first place.

Class Headers

Every Jailbreak class has a comment header like the one in the following template (with class name, author name and email address, and description substituted by suitable values):

  // ============================================================================
  // JBInterfaceHud
  // Copyright 2003 by Mychaeel <mychaeel@planetjailbreak.com>
  // $Id$
  //
  // Heads-up display for Jailbreak, showing team states and switch locations.
  // ============================================================================

The $Id$ part is automatically substituted by a file descriptor by CVS.

Section Headers

Individual sections in class source code have simple headers of their own that simplify browsing, like the following:

  // ============================================================================
  // Variables
  // ============================================================================

Common headers are "Defaults" (for default properties), "Variables" (for internally used class-level variables), "Properties" (for property variables exposed in UnrealEd), "Localization" (for variables that are subject to localization) and "Imports" (for #exec directives that import external resource files).

Function Headers

Every function (both overwritten functions and functions initially declared in this class) has a comment header like the following one that restates its name and describes, in brief terms, its purpose and effects.

  // ============================================================================
  // HackSpeechMenu
  //
  // Hacks into the speech menu in order to add a team tactics selection there.
  // Monitors the menu and adds or changes menu entries depending on the menu's
  // current state.
  // ============================================================================

Spacing and braces

Standard style for core classes is:

 (header)
// ============================================================================
(blank line)
(blank line)
class Foo ....
(blank line)
(blank line)
// ============================================================================
(first section header)

Following this:

• one blank line between section header and section
• two blank lines between a section and the following header

Function braces (and section braces such as defaults or replication) open on a line of their own, with both braces aligned to the function keyword and the intervening lines indented:

function foobar 
{
  (body)
}

Other braces open on the keyword line, close on a line of their own aligned with the keyword, with content indented:

if (something) {
  (body)
}