Skip to content

Commit

Permalink
Add hints to exercises without starter implementation (#1084)
Browse files Browse the repository at this point in the history
* 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.
  • Loading branch information
FridaTveit authored and sjwarner-bp committed Dec 15, 2017
1 parent 3eb6e52 commit 69e8ba1
Show file tree
Hide file tree
Showing 4 changed files with 134 additions and 2 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
14 changes: 13 additions & 1 deletion POLICIES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down Expand Up @@ -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.
58 changes: 58 additions & 0 deletions exercises/flatten-array/.meta/hints.md
Original file line number Diff line number Diff line change
@@ -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!
62 changes: 62 additions & 0 deletions exercises/flatten-array/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 69e8ba1

Please sign in to comment.