Description

This Document is to give an overview of Java codeing style guidelines we wish to follow at Lightning Kite. At this point we wish to follow most of the guidelines given here Android Code Guidelines. The purpose of this document therefore is to give a more brief outline, comment on some of the guidelines at the afore mentioned URL, and be able to add any additional guidelines that we wish to follow.

In the case that there is any inconsistency between this document and the one linked above, follow this document.

Don't Ignore Exceptions

This almost always is the incorrect thing to do.(First code example) The exception usually can be handled in a more appropriate way.

Acceptable alternatives

  • Throw the exception up to the caller of your method, this allows you to throw the exception up to a level where you can handle the exception gracefully and appropriately.
  • Throw a new exception that's appropriate to your level of abstraction.
  • Substitute an appropriate value in the catch block (see second code example
  • Catch the exception and throw a new Runtime Exception **Only do this if the appropriate action is for the application to crash.** At Lightning Kite this most likely will not be something that is necessary for us to do (Except perhaps for any libraries we write).
  • As a last resort you may ignore the exception, however only when you are absolutely certain that this is the appropriate action to take. Also make sure to provide a comment as to why you feel that ignoring the exception is the correct course of action in this instance.
void setServerPort(String value) {
	// don't do this.
	try {
		serverPort = Integer.parseInt(value);
	} catch (NumberFormatException exception) {}

	//yes do this.
	try {
		serverPort = Integer.parseInt(value);
	} catch (NumberFormatException ex) {
		serverPort = 80;  //default port for server
	}

}

Don't catch generic exceptions

Absolutely do not do this, it can cause bugs that are difficult to track down.

Some Alternatives

  • Catch each exception separately
  • Refactor your code to have more fine tuned error handling
  • Rethrow the exception.
try {
	someComplicatedIOFunction();        // may throw IOException
	someComplicatedParsingFunction();   // may throw ParsingException
	someComplicatedSecurityFunction();  // may throw SecurityException
} catch (Exception e) {                 //I'll just catch all exceptions.
	handleError();
}

Don't Use Finalizers

Refer to link at beginning of document.

Description:

This Document is to give an overview of Android codeing style guidelines we wish to follow at Lightning Kite. At this point we wish to follow most of the guidelines given here [Android Code Guidelines](https://source.android.com/source/code-style.html). The purpose of this document therefore is to give a more brief outline, comment on some of the guidelines at the afore mentioned URL, and be able to add any additional guidelines that we wish to follow.

Fully Qualify Imports

For example import android.widget.Button, rather than import android.widget.*

The exception to this rule is java standard libraries such as java.util and java.io

Comments

Not too concerned here with doing the Javadoc standard comments needed by the Javadoc tool. But we should comment on our classes and non trivial functions and give a brief description of what they are doing.

Write Short Methods.

This helps to keep things modular and easy to read, and lends to the principle of having your methods fulfill a single purpose, which makes your methods more testable.

Define Fields in Standard Places

Define fields either at the beginning of the file or just prior to the method that uses them.

Limit Variable Scope

The scope of local variables should be kept to a minimum. Each variable should be declared in the innermost block that encloses all uses of the variable.

The exception to the rule being when dealing with try catch blocks.

/*
*This would be the exception to the rule,  when using try catch blocks you often
*do not want to limit the scope of the variable to just the try block.
*/
Set s = null;
try {
	s = (Set) cl.newInstance();
} catch(IllegalAccessException e) {
	throw new IllegalArgumentException(cl + " not accessible");
} catch(InstantiationException e) {
	throw new IllegalArgumentException(cl + " not instantiable");
}

s.addAll(Arrays.asList(args));

Use spaces for indentation.

4 spaces for indent blocks, and 8 spaces for line wraps.

Follow field naming conventions.

  • Protected and private fields start with an m.
  • Static field names start with an s.
  • Other fields follow standard camelcasing.
  • Use all caps and underscores for public static final fields.

Use Standard Brace Style

See examples on the right.

if(someNum < MAX && someNum > MIN) {
	doSomething();
}

//I prefer the above but will grudgingly accept
if(someNum < MAX && someNum > MIN)
{
	doSomething();
}

//don't do this.
if(someNum > MAX && someNum < MIN)
	doSomething();

Limit Line Length

Limit your lines of text to be no more than 100 characters. I beleive Android Studio displays a line showing where 100 characters is by default.

Exceptions would be

  • A comment that has a url or example command that is longer than 100 characters.
  • import lines

Use Standard Java Annotations

@Deprecated, @Override, and @SuppressWarnings. Always try to eliminate warnings rather than suppress them, use @SuppressWarnings only if you feel that the warning is impossible to eliminate.

Use TODO Comments

Use this for code that can be improved or also of course something that needs to be done in the future.

Log Sparingly

Too many logs does start to look messy, besides it also decreases the performance of the app. For more info refer to the link given at the top of this document.

Follow Test Method Naming Conventions.

use underscores to separate what is being tested from the case that is being tested.

testMethod_specificCase1 testMethod_specificCase2

void testIsDistinguishable_protanopia() {
	ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
	assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
	assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
}