Download The Ultimate Tutorial: Getting Started With Kotlin

350 pages of hands-on tutorial right into your email inbox. Learn how to use state of the art development environment and build a full-fledged command-line application. You will receive free updates to the tutorial. Start learning Kotlin today!

Archive Monthly Archives: February 2018

Clean Architecture For Android


NOTE: this article is still under construction. If you want to learn more these links will be beneficial to read:

This will soon become an article on adapting these concepts to Kotlin on Android.

Enjoy the reading!

Human-Oriented Approach


So you’ve got a feature to implement. Something like “James wants to enter expense?” Who is James anyways?


James is our Persona. It is the user of our application.

James is probably an employee of some company who is on a trip to the customer site. James wants to enter expenses so that the company can keep track of costs, reimburse them to James, and charge what is appropriate to the client.

When developing user-facing applications, it is a good idea to have a Persona like that in mind. And for every feature (and everything we program) we should think carefully what kind of value James wants to get here and why.

Since we already started talking about users and their personas, let’s go all out and write a User Story.

User Story

User Story captures the following aspects:

  • Who is the Persona?
  • What feature they want or need?
  • Why is that functionality valuable for them?
  • How can a tester verify that the feature works? (Acceptance Criteria)

Let me give you a template for the first three questions:

As {Persona},
I want/need to {my desire or need},
So that I {get the value}.

That template is not necessary. It is possible to have higher quality user stories when they don’t follow any template. On the other hand, it is hard to write a user story if you never did that, so template helps a lot in the beginning.

So if you know what you are doing, feel free to skip user story template and write it as you like.

If you are still a beginner with user stories, I highly suggest the use of such template. As you get more proficient with it, you should experiment with the template more.

The User Story for the current feature seems to be:

James wants to enter an expense:

As James,
I want to be able to enter an expense,
So that I can be reimbursed,
And my company can properly bill expenses to the client.

Before you rush to implement that, you’ll want to know when are you done with the feature. For that, you’ll need to write an Acceptance Criteria.

Acceptance Criteria

Acceptance Criteria are instructions for the tester (or automation framework) to verify that our User Story is implemented correctly.

When I say tester, I mean: the person who is wearing a hat of a tester. It could be an individual member of the team. Or it could be a developer, you. It could, as well, be your Product Owner, Project Manager or Product Manager. Finally, it could be your customer or client.

Within the boundaries of this tutorial, this person will be you.

They are usually written using Given/When/Then template:

Given <pre condition>
When <user’s action>
Then <expected outcome>

If you need multiple Givens, Whens or Thens:

Given <pre condition 1>
And <pre condition 2>
And <pre condition N>

When <user’s action 1>
And <user’s action 2>
And <user’s action N>

Then <expected outcome 1>
And <expected outcome 2>
And <expected outcome N>

The precondition is the description of what state the system and the user should be in before testing this feature.

User’s action is, well, just that: how the user interacts with the program.

The expected outcome is how we expect the system to behave after said user interaction given the provided preconditions. It is mostly the user-observed behavior.

Sometimes, though, we need to capture expected outcome as non-observed behavior. To write the story in such format, we need to involve the second persona, who has access to system internals.

In the context of our business domain, it could James’ manager, Kate, who wants to see the expense reports, accept and reject them. They are going to do that in some administrative area of the software, to which James does not have access.

Most often, though, it is possible to extract the whole other user story for that persona with its acceptance criteria. That is what we should do in that case.

OK. Enough theory. Let’s write acceptance criteria for the user story:

Example User Story

As James,
I want to be able to enter an expense,
So that I can be reimbursed,
And my company can properly bill expenses to the client.

## Acceptance Criteria

Given I am on the “Home” screen
When I tap on “Add Expense” button
Then I see the form with the fields:

- Date (defaults to today for convenience)
- Amount
- Currency drop down (single option for now – Euro)
- Needs reimbursement (check box)
- Client-related (check box)
- Comment

When I enter all the data
And I tap on “Save” button
Then I see the “Expense Details” screen
And I see all the data I’ve entered

Now, that you have the acceptance criteria, you should be able to translate it to the acceptance test for the business domain of your application.


Thank you so much for reading this article. This post is a part of much more significant project iwillteachyoukotlin.com in which you are going to learn to program in Kotlin in general, and if you wish in the context of Android or/and Web development.

Android Studio Hotkey Map (for Ultimate Tutorial)


Download the hotkey map specifically designed for the Android Ultimate Tutorial: