This style-guide is somewhat of a mash-up between the existing Kotlin language style guides. The language guidance is drawn from:
- Android Kotlin style guide
- Kotlin Coding Conventions
- Google Java Style Guide.
- Ribot's Android Guidelines
- Ray Wenderlich's Kotlin Style Guide
- Adam Bennett's Kotlin Style Guide
It is possible to get Android Studio to adhere to these style guidelines, via a rather complex sequence of menus. To make it easier, we've provided a coding style that can be imported into Android Studio.
The file can be found here.
To use these settings:
- If you have a project opened, go to File > Manage IDE Settings > Import Settings and then select this zip file.
- If you are on the select project dialogue, go to Configue > Import Settings and then select this zip file.
Plugins |
---|
Android Parcelable Code Generator |
Atom Material Icons |
CodeGlance |
.ignore |
Markdown |
Material Color Palette |
One Dark Theme |
Rainbow Brackets |
String Manipulation |
- Inspiration
- Android Studio Coding Style
- Recommended Plugins for Android Studio
- Table of Contents
- File Naming
- Code Guidelines
- Language
- Kotlin Language Rules
- Declaration
- Treat Acronyms as Words
- Comments
- Semicolons
- Indentation
- Don't Ignore Exceptions
- Don't Catch Generic Exception
- Don't Use Finalizers
- Fully Qualify Imports
- When Statements
- Type Inference
- Companion Objects
- Constants vs. Variables
- Nullable Types
- Limit Variable Scope
- Visibility Modifiers
- Access Level Modifiers
- Logging guidelines
- Class Member Ordering
- Parameter Ordering in Methods
- String Constants, Naming, and Values
- Arguments in Fragments and Activities
- XML Style Rules
On the whole, naming should follow Java standards, as Kotlin is a JVM-compatible language.
Package names are similar to Java: all lower-case, multiple words concatenated together, without hypens or underscores:
BAD:
com.Krayong.funky_widget
GOOD:
com.krayong.funkywidget
Class names are written in UpperCamelCase.
For classes that extend an Android component, the name of the class should end with the name of the component.
Examples: SignInActivity
, SignInFragment
, ImageUploaderService
, ChangePasswordDialog
.
Methods are written in lowerCamelCase.
Examples: setValue
, assignUser
.
Generally, written in lowerCamelCase. Fields should not be named with Hungarian notation, as Hungarian notation is erroneously thought to be recommended by Google.
Example field names:
class MyClass {
var publicField: Int = 0
val person = Person()
private var privateField: Int?
}
Constant values in the companion object should be written in uppercase, with an underscore separating words:
companion object {
const val THE_ANSWER = 42
}
Written in lowerCamelCase.
Single character values must be avoided, except for temporary looping variables.
Resources file names are written in lowercase_underscore.
Naming conventions for drawables:
Asset Type | Prefix | Example |
---|---|---|
Action bar | ab_ |
ab_stacked.9.png |
Button | btn_ |
btn_send_pressed.9.png |
Dialog | dialog_ |
dialog_top.9.png |
Divider | divider_ |
divider_horizontal.9.png |
Icon | ic_ |
ic_star.png |
Menu | menu_ |
menu_submenu_bg.9.png |
Notification | notification_ |
notification_bg.9.png |
Tabs | tab_ |
tab_pressed.9.png |
Naming conventions for icons (taken from Android iconography guidelines):
Asset Type | Prefix | Example |
---|---|---|
Icons | ic_ |
ic_star.png |
Launcher icons | ic_launcher |
ic_launcher_calendar.png |
Menu icons and Action Bar icons | ic_menu |
ic_menu_archive.png |
Status bar icons | ic_stat_notify |
ic_stat_notify_msg.png |
Tab icons | ic_tab |
ic_tab_recent.png |
Dialog icons | ic_dialog |
ic_dialog_info.png |
Naming conventions for selector states:
State | Suffix | Example |
---|---|---|
Normal | _normal |
btn_order_normal.9.png |
Pressed | _pressed |
btn_order_pressed.9.png |
Focused | _focused |
btn_order_focused.9.png |
Disabled | _disabled |
btn_order_disabled.9.png |
Selected | _selected |
btn_order_selected.9.png |
Layout files should match the name of the Android components that they are intended for but moving the top level component name to the beginning. For example, if we are creating a layout for the SignInActivity
, the name of the layout file should be activity_sign_in.xml
.
Component | Class Name | Layout Name |
---|---|---|
Activity | UserProfileActivity |
activity_user_profile.xml |
Fragment | SignUpFragment |
fragment_sign_up.xml |
Dialog | ChangePasswordDialog |
dialog_change_password.xml |
AdapterView item | --- | item_person.xml |
Partial layout | --- | partial_stats_bar.xml |
A slightly different case is when we are creating a layout that is going to be inflated by an Adapter
, e.g to populate a ListView
. In this case, the name of the layout should start with item_
.
Note that there are cases where these rules will not be possible to apply. For example, when creating layout files that are intended to be part of other layouts. In this case you should use the prefix partial_
.
Similar to layout files, menu files should match the name of the component. For example, if we are defining a menu file that is going to be used in the UserActivity
, then the name of the file should be activity_user.xml
A good practice is to not include the word menu
as part of the name because these files are already located in the menu
directory.
Resource files in the values folder should be plural, e.g. strings.xml
, styles.xml
, colors.xml
, dimens.xml
, attrs.xml
Use en-US
English spelling.
BAD:
val colourName = "red"
GOOD:
val colorName = "red"
Fields should be defined at the top of the file.
Example:
class MyClass {
public var publicVariable: Int? // same as public int variable in java
var packagePrivate: Int? // same as int variable in java
private var privateVariable: Int? // same as private int variable in java
protected var protectedVariable: Int? // same as protected int variable in java
companion object {
public const val SOME_CONSTANT = 42 // same as public static final int variable in java
}
}
Prefer single declaration per line.
BAD:
var username:String?; var twitterHandle: String?
GOOD:
var username: String?
var twitterHandle: String?
Exactly one class per source file, although inner classes are encouraged where scoping appropriate.
Initialize the properties of a class via primary constructor parameters instead of using an init block.
BAD:
class Person(firstName: String, lastName: String, age: Int) {
val firstName: String
val lastName: String
var age: Int
init {
this.firstName = firstName
this.lastName = lastName
this.age = age
}
// ...
}
GOOD:
class Person(val firstName: String, val lastName: String, var age: Int) {
// ...
}
For formatting these primary constructors, follow the Kotlin coding conventions:
Classes with longer headers should be formatted so that each primary constructor argument is in a separate line with indentation. Also, the closing parenthesis should be on a new line. If we use inheritance, then the superclass constructor call or list of implemented interfaces should be located on the same line as the parenthesis.
For multiple interfaces, the superclass constructor call should be located first and then each interface should be located in a different line:
class Person(
id: Int,
name: String,
surname: String
) : Human(id, name),
KotlinMaker {
// ...
}
Prefer data classes for simple data holding objects.
BAD:
class Person(val name: String) {
override fun toString() : String {
return "Person(name=$name)"
}
}
GOOD:
data class Person(val name: String)
Unlike Java, direct access to fields in Kotlin is preferred.
If custom getters and setters are required, they should be declared following Kotlin conventions rather than as separate methods.
Enum classes without methods may be formatted without line-breaks, as follows:
private enum CompassDirection { EAST, NORTH, WEST, SOUTH }
Good | Bad |
---|---|
XmlHttpRequest |
XMLHTTPRequest |
getCustomerId |
getCustomerID |
url: String? |
URL: String? |
findPostById |
findPostByID |
When they are needed, use comments to explain why a particular piece of code does something. Comments must be kept up-to-date or deleted.
Avoid block comments inline with code, as the code should be as self-documenting as possible. Exception: This does not apply to those comments used to generate documentation.
Semicolons are dead to us should be avoided wherever possible in Kotlin.
BAD:
val horseGiftedByTrojans = true;
if (horseGiftedByTrojans) {
bringHorseIntoWalledCity();
}
GOOD:
val horseGiftedByTrojans = true
if (horseGiftedByTrojans) {
bringHorseIntoWalledCity()
}
Indentation is always using tabs - never spaces (NEVER). We are with Richard on this.
Indentation for blocks uses 1 tab:
BAD:
for (i in 0..9) {
Log.i(TAG, "index=" + i) // 2 spaces
}
for (i in 0..9) {
Log.i(TAG, "index=" + i) // 4 spaces
}
GOOD:
for (i in 0..9) {
Log.i(TAG, "index=" + i) // 1 tab 😃
}
There should be exactly two blank lines between methods to aid in visual clarity and organization. Whitespace within methods should separate functionality, but having too many sections in a method often means you should refactor into several methods.
Code lines should not exceed 100 characters. If the line is longer than this limit there are usually two options to reduce its length:
- Extract a local variable or method (preferable).
- Apply line-wrapping to divide a single line into multiple ones.
There are two exceptions where it is possible to have lines longer than 100:
- Lines that are not possible to split, e.g. long URLs in comments.
package
andimport
statements.
Indentation for line wraps should use 2 tabs (not the default 1):
BAD:
val widget: CoolUiWidget =
someIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line)
GOOD:
val widget: CoolUiWidget =
someIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line)
There isn't an exact formula that explains how to line-wrap and quite often different solutions are valid. However there are a few rules that can be applied to common cases.
Break at operators
When the line is broken at an operator, the break comes before the operator. For example:
longName: Int = anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne
+ theFinalOne;
Assignment Operator Exception
An exception to the break at operators
rule is the assignment operator =
, where the line break should happen after the operator.
longName: Int =
anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne + theFinalOne;
Method chain case
When multiple methods are chained in the same line - for example when using Builders - every call to a method should go in its own line, breaking the line before the .
Picasso.with(context).load("https://avatars.githubusercontent.com/u/42269590?s=400&u=88c4366ebb380a6b1069281b14cbce486948d269&v=4").into(imageView)
Picasso.with(context)
.load("https://avatars.githubusercontent.com/u/42269590?s=400&u=88c4366ebb380a6b1069281b14cbce486948d269&v=4")
.into(imageView)
Long parameters case
When a method has many parameters or its parameters are very long, we should break the line after every comma ,
loadPicture(context, "https://avatars.githubusercontent.com/u/42269590?s=400&u=88c4366ebb380a6b1069281b14cbce486948d269&v=4", mImageViewProfilePicture, clickListener, "Title of the picture")
loadPicture(context,
"https://avatars.githubusercontent.com/u/42269590?s=400&u=88c4366ebb380a6b1069281b14cbce486948d269&v=4",
mImageViewProfilePicture,
clickListener,
"Title of the picture")
Only trailing closing-braces are awarded their own line. All others appear the same line as preceding code:
BAD:
class MyClass
{
fun doSomething()
{
if (someTest)
{
// ...
}
else
{
// ...
}
}
}
GOOD:
class MyClass {
fun doSomething() {
if (someTest) {
// ...
} else {
// ...
}
}
}
Conditional statements are always required to be enclosed with braces, irrespective of the number of lines required.
BAD:
if (someTest)
doSomething()
if (someTest) doSomethingElse()
GOOD:
if (someTest) {
doSomething()
}
if (someTest) { doSomethingElse() }
You must never do the following:
fun setServerPort(value: String) {
try {
serverPort = value.toInt()
} catch (e: NumberFormatException) {}
}
While you may think that your code will never encounter this error condition or that it is not important to handle it, ignoring exceptions like above creates mines in your code for someone else to trip over some day. You must handle every Exception in your code in some principled way. The specific handling varies depending on the case. - (Android code style guidelines)
See alternatives here.
You should not do this:
try {
someComplicatedIOFunction() // may throw IOException
someComplicatedParsingFunction() // may throw ParsingException
someComplicatedSecurityFunction() // may throw SecurityException
// phew, made it all the way
} catch (e: Exception) { // I'll just catch all exceptions
handleError() // with one generic handler!
}
See the reason why and some alternatives here
We don't use finalizers. There are no guarantees as to when a finalizer will be called, or even that it will be called at all. In most cases, you can do what you need from a finalizer with good exception handling. If you absolutely need it, define a close()
method (or the like) and document exactly when that method needs to be called. See InputStream
for an example. In this case it is appropriate but not required to print a short log message from the finalizer, as long as it is not expected to flood the logs. - (Android code style guidelines)
This is bad: import foo.*;
This is good: import foo.Bar;
See more info here
To keep when
statements clean, do not call more than one function from a condition. Prefer to move these functions into a single enclosing function:
BAD:
when (aValue) {
1 -> doSomethingForCaseOne()
2 -> {
foo()
bar()
}
3 -> doSomethingForCaseThree()
}
GOOD:
when (aValue) {
1 -> doSomethingForCaseOne()
2 -> doSomethingForCaseTwo()
3 -> doSomethingForCaseThree()
}
fun doSomethingForCaseTwo() {
foo()
bar()
}
Unlike switch
statements in Java, when
statements do not fall through. Separate cases using commas if they should be handled the same way. Always include the else case.
BAD:
when (anInput) {
1 -> doSomethingForCaseOneOrTwo()
2 -> doSomethingForCaseOneOrTwo()
3 -> doSomethingForCaseThree()
}
GOOD:
when (anInput) {
1, 2 -> { doSomethingForCaseOneOrTwo() }
3 -> { doSomethingForCaseThree() }
else -> { println("No case satisfied") }
}
Type inference should be preferred where possible to explicitly declared types.
BAD:
val something: MyType = MyType()
val meaningOfLife: Int = 42
GOOD:
val something = MyType()
val meaningOfLife = 42
Companion objects, such as those for Fragment
newInstance
methods, should be defined at the bottom of a class declaration;
class MyFragment : Fragment() {
init {
Injector.INSTANCE.inject(this)
}
@Inject
lateinit var dataManager: DataManager
fun doSomething() {
// ...
}
companion object {
const val BUNDLE_VALUE_ONE = "bundle_value_one"
fun newInstance(value1: String, value2: String): MyFragment {
// ...
}
}
}
As a sidenote regarding val
properties in companion objects; accessing them from Java requires accessing the companion object too, which is ugly and not idiomatic:
String key = MyFragment.Companion.BUNDLE_VALUE_ONE;
Delcaring the property as a const val
allows you to access a property as if it was static from Java code:
String key = MyFragment.BUNDLE_VALUE_ONE;
This also inlines any access to the val
. There is a caveat though: this only works with primitives and Strings. For more information, check out this excellent article regarding constants in Kotlin.
Constants are defined using the val
keyword, and variables with the var
keyword. Always use val
instead of var
if the value of the variable will not change.
Tip: A good technique is to define everything using val
and only change it to var
if the compiler complains!
Declare variables and function return types as nullable with ?
where a null
value is acceptable.
Use implicitly unwrapped types declared with !!
only for instance variables that you know will be initialized before use, such as subviews that will be set up in onCreate
for an Activity or onCreateView
for a Fragment.
When naming nullable variables and parameters, avoid naming them like nullableString
or maybeView
since their nullability is already in the type declaration.
When accessing a nullable value, use the safe call operator if the value is only accessed once or if there are many nullables in the chain:
editText?.setText("foo")
The scope of local variables should be kept to a minimum. By doing so, you increase the readability and maintainability of your code and reduce the likelihood of error. Each variable should be declared in the innermost block that encloses all uses of the variable.
Local variables should be declared at the point they are first used. Nearly every local variable declaration should contain an initializer. If you don't yet have enough information to initialize a variable sensibly, you should postpone the declaration until you do. - (Android code style guidelines)
Always include visibility modifiers.
BAD:
val wideOpenProperty = 1
private val myOwnPrivateProperty = "private"
GOOD:
public val wideOpenProperty = 1
private val myOwnPrivateProperty = "private"
Access level modifiers should be explicitly defined for classes, methods and member variables.
Use the logging methods provided by the Log
class to print out error messages or other information that may be useful for developers to identify issues:
Log.v(String tag, String msg)
(verbose)Log.d(String tag, String msg)
(debug)Log.i(String tag, String msg)
(information)Log.w(String tag, String msg)
(warning)Log.e(String tag, String msg)
(error)
As a general rule, we use the class name as tag and we define it at the top of the file. For example:
public class MyClass {
private val TAG = MyClass::class.qualifiedName
private fun myMethod() {
Log.e(TAG, "My error message")
}
}
VERBOSE and DEBUG logs must be disabled on release builds. It is also recommended to disable INFORMATION, WARNING and ERROR logs but you may want to keep them enabled if you think they may be useful to identify issues on release builds. If you decide to leave them enabled, you have to make sure that they are not leaking private information such as email addresses, user ids, etc.
To only show logs on debug builds:
if (BuildConfig.DEBUG) Log.d(TAG, "The value of x is " + x)
There is no single correct solution for this but using a logical and consistent order will improve code learnability and readability. It is recommendable to use the following order:
- Constants
- Fields
- Constructors
- Override methods and callbacks (public or private)
- Public methods
- Private methods
- Inner classes or interfaces
Example:
public class MainActivity: Activity {
private const val TAG = this::class.qualifiedName
override val ...
override var ...
public val ....
protected val ...
val ...
private val ...
public var ...
protected var ...
var ...
private var ...
private lateinit var ...
private val abcObject: AbcObject by lazy {
AbcObject()
}
override fun onCreate() {
...
}
public suspend fun uploadData() {
...
}
private suspend fun getData() {
...
}
public fun setTitle() {
...
}
private fun setUpView() {
...
}
inner class AnInnerClass {
...
}
companion object {
public const val ...
private const val ...
fun changeView() {
...
}
}
}
If your class is extending an Android component such as an Activity or a Fragment, it is a good practice to order the override methods so that they match the component's lifecycle. For example, if you have an Activity that implements onCreate()
, onDestroy()
, onPause()
and onResume()
, then the correct order is:
public class MainActivity: Activity {
//Order matches Activity lifecycle
override fun onCreate() {}
override fun onResume() {}
override fun onPause() {}
override fun onDestroy() {}
}
When programming for Android, it is quite common to define methods that take a Context
. If you are writing a method like this, then the Context must be the first parameter.
The opposite case are callback interfaces that should always be the last parameter.
Examples:
// Context always goes first
public fun loadUser(context: Context, userId: Int): User { };
// Callbacks always go last
public fun loadUserAsync(context: Context, userId: Int, userCallback: UserCallback) { };
Many elements of the Android SDK such as SharedPreferences
, Bundle
, or Intent
use a key-value pair approach so it's very likely that even for a small app you end up having to write a lot of String constants.
When using one of these components, you must define the keys as a const val
fields in companion object
and they should be prefixed as indicated below.
Element | Field Name Prefix |
---|---|
SharedPreferences | PREF_ |
Bundle | BUNDLE_ |
Fragment Arguments | ARGUMENT_ |
Intent Extra | EXTRA_ |
Intent Action | ACTION_ |
Note that the arguments of a Fragment - Fragment.getArguments()
- are also a Bundle. However, because this is a quite common use of Bundles, we define a different prefix for them.
Example:
companion object {
// Note the value of the field is the same as the name to avoid duplication issues
const val PREF_EMAIL = "PREF_EMAIL"
const val BUNDLE_AGE = "BUNDLE_AGE"
const val ARGUMENT_USER_ID = "ARGUMENT_USER_ID"
// Intent-related items use full package name as value
const val EXTRA_SURNAME = "com.myapp.extras.EXTRA_SURNAME"
const val ACTION_OPEN_USER = "com.myapp.action.ACTION_OPEN_USER"
}
Prefer using string template to concatenate string for cleaner code.
BAD:
val language = "Android"
val sentence = "I love to code in " + language "."
GOOD:
val language = "Android"
val sentence = "I love to code in ${language}."
When data is passed into an Activity
or Fragment
via an Intent
or a Bundle
, the keys for the different values must follow the rules described in the section above.
When an Activity
or Fragment
expects arguments, it should provide a method that facilitates the creation of the relevant Intent
or Fragment
.
In the case of Activities the method is usually called getStartIntent()
:
companion object {
@JvmStatic
fun getStartIntent(context: Context, user: User): Intent {
val intent = Intent(context, ThisActivity::class.java)
intent.putParcelableExtra(EXTRA_USER, user)
return intent
}
}
For Fragments it is named newInstance()
and handles the creation of the Fragment with the right arguments:
companion object {
@JvmStatic
fun newInstance(user: User): UserFragment {
val fragment = UserFragment()
val args = Bundle()
args.putParcelable(ARGUMENT_USER, user)
fragment.setArguments(args)
return fragment
}
}
Note 1: These methods should go at the top of the class before onCreate()
.
Note 2: If we provide the methods described above, the keys for extras and arguments should be private
because there is not need for them to be exposed outside the class.
When an XML element doesn't have any contents, you must use self closing tags.
This is good:
<TextView
android:id="@+id/text_view_profile"
android:layout_width="wrap_content"
android:layout_height="wrap_content" />
This is bad :
<!-- Don't do this! -->
<TextView
android:id="@+id/text_view_profile"
android:layout_width="wrap_content"
android:layout_height="wrap_content" >
</TextView>
Resource IDs and names are written in lowerCamelCase.
IDs should be prefixed with the name of the element in lower camel case. For example:
Element | Prefix |
---|---|
TextView |
text |
ImageView |
img |
Button |
btn |
Menu |
menu |
ImageButton |
imgBtn |
Image view example:
<ImageView
android:id="@+id/imgProfile"
android:layout_width="wrap_content"
android:layout_height="wrap_content" />
Menu example:
<menu>
<item
android:id="@+id/menuDone"
android:title="Done" />
</menu>
String names start with a prefix that identifies the section they belong to. For example registration_email_hint
or registration_name_hint
. If a string doesn't belong to any section, then you should follow the rules below:
Prefix | Description |
---|---|
error_ |
An error message |
msg_ |
A regular information message |
title_ |
A title, i.e. a dialog title |
action_ |
An action such as "Save" or "Create" |
Exceptions are strings like yes
, no
, cancel
which have the same use case everywhere and are used a lot.
Unlike the rest of resources, style names are written in UpperCamelCase as they are specifies in the themes.xml
/styles.xml
.
As a general rule you should try to group similar attributes together. A good way of ordering the most common attributes is:
- View ID
- Style
- Layout Width and Layout Height
- Other layout attributes, sorted alphabetically
- Style attributes such as
gravity
ortextColor
- Value attributes such as
text
orsrc
- Remaining attributes, sorted alphabetically