discussion: Should we provide type signatures with the exercises?

[rbasso]

We can provide exercises with a stub solution, like this one:

module LeapYear (isLeapYear) where

isLeapYear :: Integer -> Bool
isLeapYear year = undefined

I believe we could make the Haskell track more enjoyable and accessible for beginners adding stubs to all exercises. This could save users from inspecting the test suites to figure out what they need to implement.

I see two possible objections to this:

1. Figuring out what is the exercise is part of the exercise
2. Some tests that currently allow polymorphic solutions would have to be restricted

About 1, I think it is too difficult for beginners, and it gets easy and boring after a while. As an example, look at our first test suite:

{-# OPTIONS_GHC -fno-warn-type-defaults #-}

import Control.Monad (unless)
import System.Exit   (exitFailure)

import Test.HUnit
    ( (~:)
    , (~=?)
    , Counts (failures, errors)
    , Test   (TestList)
    , runTestTT
    )

import LeapYear (isLeapYear)

main :: IO ()
main = do
         counts <- runTestTT isLeapYearTests
         unless (failures counts == 0 && errors counts == 0) exitFailure

isLeapYearTests :: Test
isLeapYearTests = TestList $ map test cases
  where
    test (label, year, expected) = label ~: isLeapYear year ~=? expected
    cases = [ ("leap year"                  , 1996, True )
            , ("standard and odd year"      , 1997, False)
            , ("standard even year"         , 1998, False)
            , ("standard nineteenth century", 1900, False)
            , ("standard eighteenth century", 1800, False)
            , ("leap twenty fourth century" , 2400, True )
            , ("leap y2k"                   , 2000, True ) ]

There is no single mention of the argument type of isLeapYear. Is it Int, Integer or any Integral? Should I choose? Which one is better?

I don't see what people are learning reading tests like this, specially after repeating it 70 times.

The problem with 2 is that, by allowing a "polymorphic solution/library", we end up writing unidiomatic tests, and we expose users to bad coding practices. We should allow freedom on how to implement a solution, but the interface is what defines a problem, and the problem should be well defined and clearly stated.
Also, in real life, we don't usually try to write a library to fit already written tests without any type annotations.

In #143 we met some problems related to this flexible approach. At the time It sounded like a good idea to allow it, now I believe it's undesirable from a pedagogical point of view.

Currently, only those exercises have stub solutions:

• all-your-base
• forth
• lens-person
• list-ops
• rna-transcription
• zipper

For the first exercises, we have more than 800 visible solutions, but that drops rapidly to 10 solutions in the later ones. Maybe we can get people to go a little further giving a little help with stub solutions! 😄

Should we add stubs for other exercises?

[petertseng]

Rust track also discusses whether to provide function signatures at exercism/rust#117 and it seems that Rust may move in this direction as well. Other alternatives discussed were putting it in some HINTS.md file in each exercise directory so that people who wish to figure out the signatures may do so but people who just want to get going can have it accessible.

[rbasso]

The only thing I don't like about using hints is forcing the copy/paste. I believe that at least the first exercises could avoid it.

[rbasso]

After taking a look at the discussion in exercism/rust#117, I'm still not sure if using HINTS would solve the problem for beginners here.

At least, a complete newbie would have to:

• Read the HINTS
• Discover the correct directory and filename for the solution.
• Create a new file and copy part of the contents of the HINTS to it.

All this costs time that could be used actually solving the exercise.

For more advanced users, the HINTS are not needed at all and all that's left is the mechanical work of reading the tests and writing the - usually unique - interface.

If we decide to follow the plan on #182, we could add the stub solutions as we refactor the exercises. This would certainly make the transition to Stack more pleasant to the users.

Also, it would make sense to move the language specific instructions contained in some test files to the stub solutions.

[rbasso]

Considering that the stubs solutions are part of what is being proposed in #182 to lower the bar in xHaskell, I will close this issue so we can focus the discussion there.

[kytrinyx]

Read the HINTS

This is totally not documented well, but if we have a HINTS.md file it will be included as part of the README of the problem.

[rbasso]

...if we have a HINTS.md file it will be included as part of the README of the problem.

We can have both: stub solutions and HINTS.md!

Some stub solutions cannot be too complete, because that would take all the fun out of the exercise. Right now, we are using comments to explain what needs to be implemented, but some users leave the comments in the final solution, and that is undesirable.

Maybe we can use HINTS.md to avoid having comments in the stub solution. 😄

[kytrinyx]

Maybe we can use HINTS.md to avoid having comments in the stub solution.

Haha, yes WE CAN HAVE ALL THE THINGS!

For what it's worth, I have rikki- giving feedback in the Go track to ask people to remove stub comments: https://github.com/exercism/rikki/blob/master/comments/analyzer/go/stub.md