provide implementation file

[mattetti]

As a new user, I found confusing that I didn't have a blank file with the package name and the basic API to implement.

[kytrinyx]

+1 I think this would be helpful.

[sunzenshen]

Does this need to be done with every exercise? While I agree that providing a template would be helpful for the first exercise, providing the API's may accidentally discourage newbies from considering how to name the inputs and outputs of their functions.

If an API is provided for every exercise, then there needs to be more thought about the names used, especially if the existing examples are converted. Let's take the first exercise as an example:

func IsLeapYear(i int) bool 

... was the API used in the example file. Should "i" be renamed "year"? Or "inputYear"?

Also, some of the example implementations make use of named results:
http://golang.org/doc/effective_go.html#named-results

The choice of whether to use that feature should be up to the participant, and providing an API might make some reluctant to take the alternate approach of returning results.

I think a compromise is to provide some tutorial comments with a first and only implementation template.

Something like:

// For each exercise, create an implementation file with the same package name as the provided tests.
package leap

func IsLeapYear(i int) bool {
   // To run the unit tests, run "go test" in the exercise directory, without quotes.
   // Many exercises come with benchmarks, which can be run with "go test -bench ."
   // Use the unit test results and the tests themselves to determine which function API's to implement.
   // Please run "go fmt" on your code before submitting it.
}

The potential downside of such tutorial comments is that they need to be maintained, along with the existing exercism help documentation. That, and the first exercise could change with the config.

[sunzenshen]

Another quirk with providing a template and API:
Travis CI currently fails if both the example and template implementations exist in the repository, due to multiple declarations.

Continuing with the "leap" example, example.go and leap.go would collide with each other:

leap/leap.go:4: IsLeapYear redeclared in this block
    previous declaration at leap/example.go:3

https://travis-ci.org/exercism/xgo/builds/31483810
from #98

This could change, but it's another thing to consider.

[mattetti]

I hear you, regarding naming the arguments, the following code is valid:

func IsLeapYear(int) bool {
// TODO: implement
return false
}

I'm not sure that all exercises need that but in this specific exercise it
makes things easier for first time users.
On Aug 2, 2014 1:14 AM, "Alan Shen" notifications@github.com wrote:

Another quirk with providing a template and API:
Travis CI currently fails if both the example and template implementations
exist in the repository, due to multiple declarations.

Continuing with the "leap" example, example.go and leap.go would collide
with each other:

leap/leap.go:4: IsLeapYear redeclared in this block
previous declaration at leap/example.go:3

https://travis-ci.org/exercism/xgo/builds/31483810

This could change, but it's another thing to consider.

—
Reply to this email directly or view it on GitHub
#97 (comment).

[sunzenshen]

That works. Still need to consider the case where Travis tries to test out both example.go and leap.go. Is changing the Travis CI behavior worth it for one exception? Or would it be better to figure out a workaround?

[soniakeys]

The idea of providing the API has come up before. Some exercises currently have the API documented in comments in the test code and the Go help page says to read the test code. We could add similar comments for Leap, but I'm not sure we need it in all cases. Even without looking at the test code, fetch then go test without even writing anything and the compiler tells you "undefined: IsLeapYear" for example. The read me says "Write a program that will take a year and report if it is a leap year." It doesn't seem too much guess that in Go you have to write a function that takes an int and returns a bool. Guess wrong and the compiler gives you pretty good error messages to guide you to the required API.

Also we can't ask much more from Submitting Exercises - the presented example is for Go and Leap!

[pminten]

This is an old issue and I'm not sure if it's intended to still be open, but I just wanted to add that the problem with having both a stub file and an example is easy to solve by using build tags.

The ledger test has that problem on steroids since it has two full implementations (a crappy one that the user has to refactor and a less crappy example). What I did there was to add at the top of the example.go file a comment line // +build example and at the top of the exercise file (ledger.go) a comment line // +build !example. The travis scripts run go test -tags example so they test the example file and ignore the exercise file.

[kytrinyx]

Good point. I'm not actually sure if we came to any conclusion with this. I think it could be useful to do it only for the first exercise to help first-time users / first-time Go programmers, but I actually like that most of the time it's up to the user to read the error messages and look at the test code to figure out what to do.

[soniakeys]

The first few exercises have stub files now. I think we can finally close this one.