From 69e8ba13639d90bdd783fad902c5c0385d93f618 Mon Sep 17 00:00:00 2001 From: FridaTveit Date: Fri, 15 Dec 2017 08:32:45 +0000 Subject: [PATCH] Add hints to exercises without starter implementation (#1084) * Add hints to exercises without starter implementation As exercises with difficulty 5 are the first exercises without starter implementation, they should have a hints file explaining how to fix the compiler errors that occur when an exercise doesn't have any starter implementation. This should be detailed in the policies doc. * flatten-array: regenerate README Also update description for how to generate readme as it was lacking detail. --- CONTRIBUTING.md | 2 +- POLICIES.md | 14 +++++- exercises/flatten-array/.meta/hints.md | 58 ++++++++++++++++++++++++ exercises/flatten-array/README.md | 62 ++++++++++++++++++++++++++ 4 files changed, 134 insertions(+), 2 deletions(-) create mode 100644 exercises/flatten-array/.meta/hints.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99b17afbb..78b21a710 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -171,7 +171,7 @@ You can do this by: 2. Clone [the problem-specifications repository](https://github.com/exercism/problem-specifications). - 3. Run `configlet generate . --only name_of_new_exercise` from the root of this repository. + 3. Run `configlet generate . --only name_of_new_exercise --spec-path path_to_problem_specifications` from the root of this repository. * Check if there is canonical data for the exercise you're adding. This can be found at `https://github.com/exercism/problem-specifications/tree/master/exercises/EXERCISE-SLUG/canonical-data.json`. diff --git a/POLICIES.md b/POLICIES.md index fb34235e7..64f1a5cd7 100644 --- a/POLICIES.md +++ b/POLICIES.md @@ -17,7 +17,7 @@ Our policies are not set-in-stone. They represent directions chosen at a point i | Track Event | Policies to review | |:------------|:-----------------| -| Exercise added/updated | [Prefer instance methods](#prefer-instance-methods); [Avoid using final](#avoid-using-final); [Adhere to best practices](#adhere-to-best-practices); [Starter implementations](#starter-implementations); [Ignore noninitial tests](#ignore-noninitial-tests); [Multiple file submissions](#multiple-file-submissions); [Name test class after class under test](#name-test-class-after-class-under-test) +| Exercise added/updated | [Prefer instance methods](#prefer-instance-methods); [Avoid using final](#avoid-using-final); [Adhere to best practices](#adhere-to-best-practices); [Starter implementations](#starter-implementations); [Ignore noninitial tests](#ignore-noninitial-tests); [Multiple file submissions](#multiple-file-submissions); [Name test class after class under test](#name-test-class-after-class-under-test); [Add hint for the first exercises without starter implementation](#add-hint-for-the-first-exercises-without-starter-implementation) | Track rearranged | [Starter implementations](#starter-implementations); [Multiple file submissions](#multiple-file-submissions) | | New issue observed in track | [Good first patches](#good-first-patches) | | "Good first patch" issue completed | [Good first patches](#good-first-patches) | @@ -79,3 +79,15 @@ References: [[1](https://github.com/exercism/java/issues/395#issue-215734887)] > The exception to this is if the tests are split into several test classes where each test class tests different functionality. In that case each class should be named `SomeClassNameFunctionalityTest` where `Functionality` is the name of the functionality to be tested in that class. See the [clock exercise](https://github.com/exercism/java/tree/master/exercises/clock) as an example. References: [[1](https://github.com/exercism/java/issues/697)] + +### Add hint for the first exercises without starter implementation + +> According to the starter implementation policy, any exercise with difficulty 4 or lower should have starter implementation. +> Any exercise with difficulty 5 or above will have no starter implementation (unless its signature is very complicated). +> This could be confusing to users when tackling their first exercise with difficulty 5 when they are used to starter implementation being provided. + +> Therefore a hints.md file should be added to the .meta directory for every exercise with difficulty 5. +> This file should explain what they need to do when there is no starter implementation. +> The files should all be the same so you can copy it from any other exercise with difficulty 5, e.g. [flatten-array](https://github.com/exercism/java/tree/master/exercises/flatten-array/.meta/hints.md). + +> We add the file to every exercise with difficulty 5 because the structure of the track means that we don't know which exercise will be the first one without starter implementation that a user will be faced with. diff --git a/exercises/flatten-array/.meta/hints.md b/exercises/flatten-array/.meta/hints.md new file mode 100644 index 000000000..53b4dedd1 --- /dev/null +++ b/exercises/flatten-array/.meta/hints.md @@ -0,0 +1,58 @@ +Since this exercise has difficulty 5 it doesn't come with any starter implementation. +This is so that you get to practice creating classes and methods which is an important part of programming in Java. +It does mean that when you first try to run the tests, they won't compile. +They will give you an error similar to: +``` + path-to-exercism-dir\exercism\java\name-of-exercise\src\test\java\ExerciseClassNameTest.java:14: error: cannot find symbol + ExerciseClassName exerciseClassName = new ExerciseClassName(); + ^ + symbol: class ExerciseClassName + location: class ExerciseClassNameTest +``` +This error occurs because the test refers to a class that hasn't been created yet (`ExerciseClassName`). +To resolve the error you need to add a file matching the class name in the error to the `src/main/java` directory. +For example, for the error above you would add a file called `ExerciseClassName.java`. + +When you try to run the tests again you will get slightly different errors. +You might get an error similar to: +``` + constructor ExerciseClassName in class ExerciseClassName cannot be applied to given types; + ExerciseClassName exerciseClassName = new ExerciseClassName("some argument"); + ^ + required: no arguments + found: String + reason: actual and formal argument lists differ in length +``` +This error means that you need to add a [constructor](https://docs.oracle.com/javase/tutorial/java/javaOO/constructors.html) to your new class. +If you don't add a constructor, Java will add a default one for you. +This default constructor takes no arguments. +So if the tests expect your class to have a constructor which takes arguments, then you need to create this constructor yourself. +In the example above you could add: +``` +ExerciseClassName(String input) { + +} +``` +That should make the error go away, though you might need to add some more code to your constructor to make the test pass! + +You might also get an error similar to: +``` + error: cannot find symbol + assertEquals(expectedOutput, exerciseClassName.someMethod()); + ^ + symbol: method someMethod() + location: variable exerciseClassName of type ExerciseClassName +``` +This error means that you need to add a method called `someMethod` to your new class. +In the example above you would add: +``` +String someMethod() { + return ""; +} +``` +Make sure the return type matches what the test is expecting. +You can find out which return type it should have by looking at the type of object it's being compared to in the tests. +Or you could set your method to return some random type (e.g. `void`), and run the tests again. +The new error should tell you which type it's expecting. + +After having resolved these errors you should be ready to start making the tests pass! diff --git a/exercises/flatten-array/README.md b/exercises/flatten-array/README.md index 243775d9b..956d28b20 100644 --- a/exercises/flatten-array/README.md +++ b/exercises/flatten-array/README.md @@ -10,6 +10,68 @@ input: [1,[2,3,null,4],[null],5] output: [1,2,3,4,5] +# Java Tips + +Since this exercise has difficulty 5 it doesn't come with any starter implementation. +This is so that you get to practice creating classes and methods which is an important part of programming in Java. +It does mean that when you first try to run the tests, they won't compile. +They will give you an error similar to: +``` + path-to-exercism-dir\exercism\java\name-of-exercise\src\test\java\ExerciseClassNameTest.java:14: error: cannot find symbol + ExerciseClassName exerciseClassName = new ExerciseClassName(); + ^ + symbol: class ExerciseClassName + location: class ExerciseClassNameTest +``` +This error occurs because the test refers to a class that hasn't been created yet (`ExerciseClassName`). +To resolve the error you need to add a file matching the class name in the error to the `src/main/java` directory. +For example, for the error above you would add a file called `ExerciseClassName.java`. + +When you try to run the tests again you will get slightly different errors. +You might get an error similar to: +``` + constructor ExerciseClassName in class ExerciseClassName cannot be applied to given types; + ExerciseClassName exerciseClassName = new ExerciseClassName("some argument"); + ^ + required: no arguments + found: String + reason: actual and formal argument lists differ in length +``` +This error means that you need to add a [constructor](https://docs.oracle.com/javase/tutorial/java/javaOO/constructors.html) to your new class. +If you don't add a constructor, Java will add a default one for you. +This default constructor takes no arguments. +So if the tests expect your class to have a constructor which takes arguments, then you need to create this constructor yourself. +In the example above you could add: +``` +ExerciseClassName(String input) { + +} +``` +That should make the error go away, though you might need to add some more code to your constructor to make the test pass! + +You might also get an error similar to: +``` + error: cannot find symbol + assertEquals(expectedOutput, exerciseClassName.someMethod()); + ^ + symbol: method someMethod() + location: variable exerciseClassName of type ExerciseClassName +``` +This error means that you need to add a method called `someMethod` to your new class. +In the example above you would add: +``` +String someMethod() { + return ""; +} +``` +Make sure the return type matches what the test is expecting. +You can find out which return type it should have by looking at the type of object it's being compared to in the tests. +Or you could set your method to return some random type (e.g. `void`), and run the tests again. +The new error should tell you which type it's expecting. + +After having resolved these errors you should be ready to start making the tests pass! + + # Running the tests You can run all the tests for an exercise by entering