Skip to content

Latest commit

 

History

History
287 lines (192 loc) · 8.02 KB

TUTORIAL.md

File metadata and controls

287 lines (192 loc) · 8.02 KB
Raw

NOTE: You can also view the HTML version of this file here: https://github.com/exercism/kotlin/blob/master/exercises/hello-world/TUTORIAL.md

Introduction

Welcome to the first exercise on the Kotlin track!

This is a step-by-step guide to solving this exercise.

Each exercise comes with a set of tests. The first pass through the exercise is about getting all of the tests to pass, one at a time.

If you have not installed the Java Development Kit and Gradle, you must do so now. For help with this, see: http://exercism.io/languages/kotlin/installation

This guide picks-up where Running the Tests (in Kotlin) left off. If you haven't reviewed those instructions, do so now.

The following instructions work equally well on Windows, Mac OS X and Linux.

Exercise Structure

When you fetch a new Kotlin exercise, you will receive:

  • one or more test files (always). These live in the src/test/kotlin directory and define a set of tests that our solution must satisfy before we can safely declare that it is working.
  • one or more starter files (initially). If provided, these live in the src/main/kotlin directory and define shells of the classes you will need in order to solve the current problem.

Solving "Hello World!"

Step 1: Run the tests against the starter solution

Use Gradle to run the tests:

$ gradle test

This command does a lot and displays a bunch of stuff. Let's break it down...

:compileKotlin
w: /Users/jtigger/exercism/exercises/kotlin/hello-world/src/main/kotlin/HelloWorld.kt: (1, 11): Parameter 'name' is never used
:compileJava UP-TO-DATE
:copyMainKotlinClasses
:processResources UP-TO-DATE
:classes UP-TO-DATE

Each line that begins with a colon (like :compileKotlin) is Gradle telling us that it's starting that task. The first five tasks are about compiling the source code of our solution. We've done you a favor and included just enough code for the solution that it compiles.

When a task is successful, it generally does not output anything. This is why :copyMainKotlinClasses does not produce any additional output.

A task may succeed but warn of a potential problem. This is what we see from :compileKotlin. The Kotlin compiler tells us that on line 1, 11 characters in of the HelloWorld.kt file, there is a parameter called name that was declared but never used. Usually, warnings are helpful and should be heeded. We'll address this warning soon enough, but we're okay for now.

The next five tasks are about compiling source code of the tests.

:compileTestKotlin
:compileTestJava UP-TO-DATE
:copyTestKotlinClasses
:processTestResources UP-TO-DATE
:testClasses UP-TO-DATE

... with both sets of source code successfully compiled, Gradle turns to running the task you asked it to: executing the tests against the solution.

:test


BinaryTreeTest > helloWorldTest FAILED
    org.junit.ComparisonFailure: expected:<[Hello, World!]> but was:<[]>
        at org.junit.Assert.assertEquals(Assert.java:115)
        at org.junit.Assert.assertEquals(Assert.java:144)
        at BinaryTreeTest.helloNoName(BinaryTreeTest.kt1 test completed, 1 failed
:test FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':test'.
> There were failing tests. See the report at: file:///Users/jtigger/exercism/exercises/kotlin/hello-world/build/reports/tests/index.html

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

BUILD FAILED

Total time: 7.473 secs

Seeing the word "fail" might give you the impression you've done something horribly wrong! You haven't. It's a whole lot of noise over a single test not passing.

Let's focus in on the important bits:

BinaryTreeTest > helloWorldTest FAILED
    org.junit.ComparisonFailure: expected:<[Hello, World!]> but was:<[]>

...is read: "Within the test class named BinaryTreeTest, the test method helloWorldTest did not pass because the solution did not satisfy an assertion. Apparently, we expected to see the string 'Hello, World!' but a blank string was returned instead.

The last line of the stack trace tells us exactly where this unsatisfied assertion lives:

        at BinaryTreeTest.helloWorldTest(BinaryTreeTest)

Looks like the scene of the crime is on line 10 in the test file.

Knowing these two facts,

  1. the return value was not what was expected, and
  2. the failure was on line 10 of the test,

we can turn this failure into success.

Step 2: Fix the Test!

In your favorite text editor, open `src/test/kotlin/BinaryTreeTest.ktgo to line 10.

assertEquals("Hello, World!", hello())

The test is expecting that hello(), returns "Hello, World!". Instead, hello() is returning "". Let's fix that.

Open src/main/kotlin/HelloWorld.kt.

fun hello(): String {
   return ""
}

Let's change that to return the expected string:

fun hello(): String {
   return "Hello, World!"
}

Save the file and run the tests again:

$ gradle test
:compileKotlin
:compileJava UP-TO-DATE
:copyMainKotlinClasses
:processResources UP-TO-DATE
:classes UP-TO-DATE
:compileTestKotlin
:compileTestJava UP-TO-DATE
:copyTestKotlinClasses UP-TO-DATE
:processTestResources UP-TO-DATE
:testClasses UP-TO-DATE
:test

BinaryTreeTest > helloWorldTest PASSED

BUILD SUCCESSFUL

Total time: 7.318 secs

"BUILD SUCCESSFUL"! Woohoo! :) You can see that helloWorldTest() test is now passing.

Congratulations!

Submitting your first iteration

With a working solution that we've reviewed, we're ready to submit it to exercism.io.

$ exercism submit src/main/kotlin/HelloWorld.kt

Next Steps

From here, there are a number of paths you can take.

Move on to the next exercise

There are many more exercises you can practice with. Grab the next one!

$ exercism fetch kotlin

Review (and comment on) others' submissions to this exercise

The heart of Exercism is the conversations about coding practices. It's definitely fun to practice, but engaging with others both in their attempts and your own is how you get feedback. That feedback can help point out what you're doing well and where you might need to improve.

Some submissions will be nearly identical to yours; others will be completely different. Seeing both kinds can be instructive and interesting.

Note that you can only view submissions of others for exercises you have completed yourself. This enriches the experience of reading others' code because you'll have your own experience of trying to solve the problem.

Here's an up-to-date list of submissions on the Kotlin track:

http://exercism.io/tracks/kotlin/exercises

Submit another iteration

You are also encouraged to consider additional "requirements" on a given exercise.

For example, you could add a test or two that requires that the greeting use the capitalized form on the person's name, regardless of the case they used.

In that situation, you'd:

  1. add a new test setting up that new expectation,
  2. implement that in the code (the same process we just went through together, above).
  3. review your code for readability and refactor as you see fit.

Exercism practitioners who "play" with each exercise — over trying to go as fast as they can through the stream of exercises — report deep rewards.

Contribute to Exercism

The entire of Exercism is Open Source and is the labor of love for more than 100 maintainers and many more contributors.

A starting point to jumping in can be found here:

https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md

Regardless of what you decide to do next, we sincerely hope you learn and enjoy being part of this community. If at any time you need assistance do not hesitate to ask for help:

http://exercism.io/languages/kotlin/help

Cheers!