Code conventions

Forge-android follows android's code style recommendations with few additions.

Here you can download Android studio XML file with the style definitions.

Right margin is set to 120 ([why?](Right margin 120)).

Directory structure and file naming of the java files

Usual directory structure for Android project that uses forge-android is the following:

• main/java/package
  • app - or application name. Contains the Application class and other global (app context) classes as abstract base activities
  • dagger - dagger modules and component definitions
  • data - classes related to data storage/communication. Usually POJOs, DB and 'value' classes.
  • dialogs - global dialogs (dialog fragment)
  • misc - everithing that does not belong to other directory
  • units - All [Forge app units](Forge app unit), i.e. your activities and companion classes
  • your_dir - feel free to create new dirs to group related classes in case they don't belong to any of the other dirs described above.

Naming and structure of items in units directory

Each subdirectory in units must contain classes related to the given [Forge app units](Forge app unit). For example the main subdir will contain:

• ActLogin - activity class
• ResLogin - interface class of the [resident component](Resident component)
• ResLoginImpl - implementation of the resident component

If some other class is closely related to the given unit AND not used by any other unit you may put it in the directory of the unit. Best candidates are dialog fragments that are shown only by this unit. That way related classes are grouped in one directory thus making it is convenient to work with them (this is in sharp contrast to other frameworks' recommendations to group classes in directories based on the parent class e.g. put all activities in activities dir, all fragments in 'fragments' dir, etc. When you work on a given activity you have to constantly look for the other related classes in some other dirs which is inconvenient and suboptimal).

Naming the unit directory

Chose a short name that describes the main function of the unit. Good names are login, manage_user, user_list. When the name is more than one word use underscore for separator. Use only lowercase.

Naming of the unit components

Prefix Activities with Act like ActMain, ActLogin. Prefix resident interface with Res like ResMain, ResLogin. Prefix resident implementation with Res and suffix it with Impl like ResMainImpl, ResLoginImpl. Prefix Fragments with Fra like FraMain, FraLogin.

Naming in res directory

Naming in res/layout directory

Activity layouts: layout file for ActUserManage should be act__user_manage.xml, i.e. use 2 underscores to separate act from the rest of the name and one underscore to separate the words.

Fragment layouts: layout file for FraUserManage should be fra__user_manage.xml

List view rows: prefix with lvr__ (two underscores)

The idea of the two underscores is to provide more readability. It separates clearly the type of the layout, e.g. Activity from the name of the layout. You will appreciate that when you have 50+ files in the layouts/ directory.

Naming in res/menu directory

Menu XML files must have the same name as the activity layout file like act__user_manage.xml for ActUserManage.

build_conf.xml

Application that use Forge framework usually contain a build_conf.xml in the res/values/ directory which contains values specific for the given type of build. For example there will be one default build_conf.xml which will be used by debug build and one in app/src/release/res/values/ directory for the release build.

Naming in layout files

IDs

View's IDs should use names like:

• Buttons - prefix with btn_. Example: +id/btn_login
• EditText - prefix with et_. Example: +id/et_username
• TextView - prefix with tv_. Example: +id/tv_info
• ListView - prefix with lv_. Example: +id/lv_users
• container - prefix with v_. Example: +id/v_login_box

Strings

One of the biggest messes becomes when one and the same string is referenced by several layouts and during the life of the app layouts and the context change and at some point someone decides to change the string value considering just one context and thus making the string look out of place in the other contexts. To avoid that we classify the strings in two categories:

1. Global strings which have prefix global_ and are usually used for global button labels like global_ok, global_close, global_cancel, etc.

2. Layout specific strings that are used and referred by only one layout file. Such string should have names that are composed by the name of the layout and the id of the view separated by two underscores. For example: "act__admin_user_create__et_password", "act__user_manage__tv_disabled". Please avoid the temptation to refer one and the same string from two or more layouts. Over time layouts will change, context will change and at some point if you decide to change the string value you may (will) forget to check if it still makes sense in all contexts.