Java Style Guide for Smarp mobile projects.

Introduction

Code that looks familiar is easier to understand and therefore also easier to review, debug and maintain. To ensure that code looks familiar to all developers on the project it’s important to agree on a common set of style guidelines.

This document provides guidelines for low level coding practices such as how to indent code and how to name types and variables. Many of the stylistic choices are subjective and different developers may have different opinions about them. Keep in mind however, that having a consistent style is more important than to satisfy each individual developers preference.

Guiding Principles

Strive to make your code compile without warnings. This rule informs many style decisions.

Use the Java naming conventions described in the Java Style Guide Naming.

Where to put code

Packages and file names

|-- data
|   |-- repositories
|   |   |-- LikeRepository.java
|   |   `-- LikeRepositoryInterface.java
|   |-- local
|   |   |-- PermanentStorage.java
|   |   `-- MemoryStorage.java
|   |-- remote
|   |    `-- Server.java
|   `-- DataProviderInterface.java
|-- domain
|   |-- entities
|   |   |-- Bookmark.java
|   |   `-- Like.java
|    `-- usecases
|       |-- LikeSendCallback.java
|       |-- LikeUseCases.java
|       `-- LikeUseCasesInterface.java
`-- presentation
    |-- navigation
    |   `-- Navigator.java
     `-- channelSubscription
        |-- ChannelSubscriptionActivity.java
        |-- ChannelSubscriptionActivityInterface.java
        |-- ChannelSubscriptionActivityPresenter.java
        |-- ChannelSubscriptionActivityPresenterInterface.java
        `-- SelectedItemChangedCallback.java

How to name

Presenter methods called by the view

onInit()
onButtonClicked()
onTextChanged()
onSearchTriggered()
onDataChanged()
onQueryChanged()

View methods called by the presenter

init/setUp()
findViews()
setUIElementColor()
setUIElementText()
setUIElementClickListener()
navigateToNextScreen()
showUIElement()
hideUIElement()
enableUIElement()
disableUIElement()

Package

Package names should be all lower case without underscores or other special characters. Don’t use plural form. Follow the convention of the standard API which uses for instance java.lang.annotation and not java.lang.annotations.

+ Preferred: follow the convention of standard java API

java.lang.annotation

- Not Preferred

java.lang.annotations
com.example.deepSpace
com.example.deep_space

checkstyle

• PackageName

Class, Interface and Enum

Class and enum names should typically be nouns. Interface names should typically be nouns or adjectives ending with …able. Use mixed case with the first letter in each word in upper case. Use whole words and avoid using abbreviations. Format an abbreviation as a word if the it is part of a longer class name.

+ Preferred: follow the convention of standard java API

class EmptyCell
class RunningMode
interface Expandable
class XmlParser
enum ServerResponse

- Not Preferred

class Empty  // Too generic
class Running // Not a noum
class XMLParser // Abbreviation should be formatted as 'Xml'
class BtnAwesome // Abreviation of button

checkstyle

• ClassTypeParameterName
• InterfaceTypeParameterName

Methods

Method names should typically be verbs or other descriptions of actions. Use mixed case with the first letter in lower case.(Camel Case)

+ Preferred: Short, concise and descriptive

public void expand()
public boolean isExpanding()
public State getState()

- Not Preferred

public boolean expanding()
public State GetState()
public int get_index()

checkstyle

• MethodName

Constants

All in uppercase

+ Preferred: All in upper case, using underline is not prohobited

String SERVER_NAME
String SOCNET_TYPE

- Not Preferred

String Server_Name
String SOCNETTYPE
String SERVERName

checkstyle

• ConstantName

Parameters and local variables

Variable names should be in mixed case with the first letter in lower case.

+ Preferred: Short, concise and descriptive, lower camel case

int currentIndex;
boolean dataAvailable;
String newCustomerId

- Not Preferred

int current_index;
boolean DataAvailable;
String newCustomerID;

checkstyle

• LocalVariableName
• ParameterName
• MemberName
• TypeName

UI elements

Use the whole name of the element without the UI prefix. After that it can be followed by a description

+ Preferred: Short, concise and descriptive

TextView textViewFirstName
TextView textViewLastName
Button buttonShareToFacebook
Button buttonShareToTwitter
ImageView imageViewProfileAvatar
ImageView imageViewLogo
URL urlProfileAvatar
RecyclerView recyclerViewShareHistory
...

- Not Preferred

LinearLayout googleButton;
LinearLayout linkedInButton;
ButtonMuseo loginButtonPassword;
TextMuseo invalidPasswordHint;
InputMethodManager imm;
LinearLayout passwordBlocked;
TextMuseo errorText;
ImageButton xButton;
IconButton mBtnCheckBox;

checkstyle

• AbbreviationAsWordInName

Data dictionary objects

Use the whole name of the object and append it with usage purpose.

+ Preferred: Short, concise and descriptive

HashMap<Object, Object> hashMap;
HashMap<Object, Object> hashMapPageReference;
Map<Object, Object> map;
Set<Object> set;
LinkedList<Object> linkedList;
ArrayList<Object> arrayListChannel;
List<CommentItem> listComment;
List<String> listComment;
SQLiteHelper sqliteHelper;
Cursor cursor;

- Not Preferred

HashMap<String, Integer> socnetShared;
HashMap<Integer, Fragment> mPageReferenceMap;
List<String> twitterCommentSet;
List<CommentItem> comments;
List<String> CommentSet;
ArrayList<Object> channelList;

checkstyle

• MemberName
• AbbreviationAsWordInName

Test methods

Example template of test method signatures is testWhatYouAreTestingShouldWhatIsExpected

+ Preferred: "test"+WhatYouAreTesting+OptionalCondition+"Should"+WhatIsExpected

testClickApproveButtonShouldChangeUIToApprove();
testClickApproveButtonWithNoInternetShouldChangeUIToApprove();

- Not Preferred

testFirstLeaderBoardMustBeCalled();

checkstyle

• MethodName

Redundant Parentheses

Variable names shoRedundant grouping parentheses (i.e. parentheses that does not affect evaluation) may be used if they improve readability. Redundant grouping parentheses should typically be left out in shorter expressions involving common operators but included in longer expressions or expressions involving operators whose precedence and associativity is unclear without parentheses. Ternary expressions with non-trivial conditions belong to the latter. The entire expression following a return keyword must not be surrounded by parentheses.

+ Preferred: Short, concise and descriptive

return flag ? "yes" : "no";
String cmp = (flag1 != flag2) ? "not equal" : "equal";

- Not Preferred

return (flag ? "yes" : "no");

References

• Java Style Guidelines (Draft, v6)
• Twitter Java Style Guide
• Code Conventions for the Java TM Programming Language
• Sourcefourge checkstyle