3/18/2010

ProKarma BlackBerry Development Guidelines

1 General Standards / Conventions
1.1 Compiler warnings are treated as errors. This eliminates the possibility of problems or bugs caused by ignored errors during compilation. 1.2 Use of the pre-processor is strongly discouraged and is ONLY acceptable in situations related to platform support 1.3 When using try/catch blocks, a catch block implementation must NEVER be empty. At the very least, it should be logged to the debug output stream. 1.4 Avoid "quick and dirty" fixes and solutions in an effort to save time. These types of changes will only reduce the stability of code over a long period of time. Examples: Changing font sizes to avoid text wrapping or truncation issues. Hard-coding screen or field dimensions based on a particular targeted device. Using the preprocessor to add code targeted to one specific device or platform.

1.5 Avoid narrow focus when changing code to fix a bug or when planning development. Examples: Making changes low-level to widely used code to fix one very specific high- level problem. Targeting a particular device or platform with plans to "come back later" and catch up the rest the rest.

2 Coding Standards
The coding conventions defined in the Sun Java Programming Coding Conventions document should be followed under all circumstances. The following sections outline some minor exceptions as well summarize some of the most important of these conventions. References to the Sun document are included where appropriate. Page 1 of 9

3/18/2010 http://java.sun.com/docs/codeconv/

2.1 Javadoc conventions

2.1.1 There should be no dates or versioning in javadoc comments. 2.1.2 All files contain a standard Javadoc comment header that includes the filename, project name, copyright information, and author declarations for anybody that has contributed code to this particular file. Standard Javadoc Header: /** * Filename.java * * Project Name * Copyright 2010 ProKarma, Inc. * * @author Ambrose Krapacs (akrapacs@prokarma.com) * @author Jayson Lewis (jlewis@prokarma.com) */

2.2 Source Files

2.2.1 Java source files contain no more than one class or interface definition (not counting inner classes). 2.2.2 Source code within a file should be organized in a consistent manner. (SUN 3.1.3) 1 File/Class documentation comment 2 package statement 3 import statements 4 Class or interface declaration 5 Class static variables 6 Class member (instance) variables 7 Constructors 8 Methods

2.3 Naming Conventions

Page 2 of 9

3/18/2010 2.3.1 Class names should be nouns, in mixed case with the first letter of each internal word capi- talized. Try to keep your class names simple and descriptive. Use whole wordsavoid acronyms and abbreviations (unless the abbre- viation is much more widely used than the long form, such as URL or HTML). (SUN 9) Examples: class Raster; class ImageSprite; 2.3.2 Interface names should be capitalized like class names. (SUN 9) Examples: interface RasterDelegate; interface Storing; 2.3.3 Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized. Examples: run(); runFast(); getBackground(); 2.3.4 All instance, class, and local variables are in mixed case with a lower-case first letter. Internal words start with capital letters. (SUN 9) Variable names should be short yet meaningful. The choice of a variable name should be mnemonic that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary throwaway variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters. Examples: int i = 0; char cp = null; float myWidth = 0.0f; 2.3.5 Class instance are prefixed with a lowercase "m". Examples: Page 3 of 9

3/18/2010 private int mIntVar = 0; private long mLongVar = 0L; 2.3.6 The names of variables declared as class constants should be all uppercase with words separated by under-scores (_). (SUN 9) Examples: static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1;

2.4 Declarations and Statements

2.4.1 There should be no more than 1 declaration per line and all declarations should be placed at the beginning of a block. (SUN 6.1-6.2) Correct Example: private void int var1 = int var2 = int var3 = methodName() { 1; 2; 3;

if (var1 == 0) { int var2 = 0; ... }

Incorrect Example: private void methodName() { someMethodCall(); int var1 = 1, int var2 = 2, int var3 = 3; while(var1 < 10) { var1++; String str = ""; } } float newVar = System.currentTimeMillis();

2.4.2 All declarations should be initialized to a default value. (SUN 6.3) Correct Example: Page 4 of 9

3/18/2010 private String strVar = ""; private Object objVar = null; public static final int FINAL_VAR = 0; private static ObjectName mInstance = null; Incorrect Example: private String strVar, strVar2; private int intVar; private long longVar; 2.4.3 There should be no more than 1 simple statement per line and statements should never be joined with a comma. (SUN 7.1-7.2) Correct Example: argv++; argc++; System.out.print(error); System.exit(1); Incorrect Example: argv++; argc++; System.out.print(error), System.exit(1);

2.5 Java Import statements

2.5.1 Import statements should be organized alphabetically and the use of wildcards in import statements should be avoided.

2.6 Curly Braces and Parenthesis

2.6.1 Opening curly braces are always on the same line as the scope declaration preceded by a space. Closing braces are always on a new line unless they are a part o f a multi- level compound statement chain, in which they on the same line as the following keyword and followed by a space. (SUN 6.4, 7.2-7.9) Correct Example:

Page 5 of 9

3/18/2010 public class ClassDef { public ClassDef (String var) { try { if (var != null) { do { ... } while(...); } else if (var == null) { ... } else { ... } } catch (Exception e) { ... } } } Incorrect Examples: public class ClassDef { public ClassDef (String var){ try { if (var != null) { do { ... } while(...); } else if (var == null){} else{} } catch (Exception e){ } } } 2.6.2 Curly braces are NEVER omitted with logic statements or loops. (SUN 7.4) Correct Example:

Page 6 of 9

3/18/2010 if (oneLine) { while (true) { bracesAreStillRequired(); } } Incorrect Example: if (oneLine) while (true) bracesAreStillRequired(); 2.6.3 Opening parenthesis in method declarations and calls are NOT preceded or followed by a space and closing parenthesis are never preceded by a space. (SUN 6.4, 7.2-7.9) Correct Example: public void funtionName(int var0) { callSomeFunc(var0); callAnotherFunc(var0, "StrVar", new Integer(0)); } Incorrect Example: public void funtionName ( int var0 ) { callSomeFunc( var0 ); callAnotherFunc ( var0, "StrVar", new Integer(0) ); } 2.6.4 Opening parenthesis in compound statements are always preceded by a space and never followed by a space and closing parenthesis are never preceded by a space. (SUN 7.4-7.9) Correct Example: if (isTrue) { while (true) { ... } } Incorrect Example:

Page 7 of 9

3/18/2010 if(isTrue) { while( true ) { ... } }

2.7 White Space

Spaces should be used in logic operators, variable assignments, function declarations, lists, and anywhere that would benefit from the spacing with respect to readability. 2.7.1 Tab characters are not to be used. Editors should be configured to use 4 spaces in place of a tab. (SUN 4) 2.7.2 Spaces should follow comma in parameter Lists in method calls and declarations (SUN 8.2) Correct Example: public void functionName (int arg0, String arg1) { callFunc(arg0, arg1); } Incorrect Example: public void functionName(int arg0,String arg1) { callFunc(arg0,arg1); } 2.7.3 Spaces should precede and follow all logic operators in all logic comparisons (SUN 8.2) Correct Example: if (x > 0 && y <= 25) { while (x < 10) { x++; } for (int j = y; j < 100; j++) { j++; } } Incorrect Example:

Page 8 of 9

3/18/2010 if (x>0&&y<=25) { while(x<10) { x++; } for(int j=y;j<100;j++) { j++; } } 2.7.4 Spaces should precede and follow the equals sign in all assignments (SUN 8.2) Correct Example: x = 5; mVariable = 25; Incorrect Example: x=5; mVariable=25; 2.7.5 Spaces should fold all commas in lists associated with array declarations (SUN 8.2) Correct Example: private static final String[] STRINGS = new String[] { "one", "two", "three", "four", "five" }; Incorrect Example: private static final String[] STRINGS = new String[] { "one","two","three","four","five" };

Page 9 of 9