exercism
Add section to exercise READMEs for input/output format?
In the Anagram README:
Given "listen" and a list of candidates like "enlists" "google" "inlets" "banana" the program should return a list containing "inlets".
but not all exercises lay things out so clearly. It's possible to check the tests, of course, but I think it might be better to make it clear up front. At least for less experienced programmers like myself.
I'm imagining something like:
Valid inputs: One of the chars \A, \T, \C, or \G
Valid output: An integer
for nucleotide-count/nucleotide-counts
Valid inputs: A string containing the chars A, T, C, or G
Valid output: A map of the format {\A int, \T int, \G int, \C int}
I'd be happy to start doing it myself if people think it's a good idea.
After working on the exercise stub files I think that it might be more helpful to make sure that each file has predefined argument names and doc strings to clarify valid inputs and outputs, like the exercises beer-song and run-length-encoding already have.
It could still be nice to have the values clearly spelled out in the README, but now that I understand better how the README files are generated I get the impression that it would be more difficult to do.
This is just speculation now (pun intended), but I think that long-term it would be nice to integrate clojure.spec into the test-suite/documentation for the Clojure track. Since it's part of the language itself I expect it will be integral to the way many (if not most) people use Clojure in the real world, and of course it would really help with requirements documentation.
Obviously this would be a major project and the maintainers are already very busy, and besides being new to Exercism, I haven't actually had experience working with spec yet, so I don't feel ready yet to take it upon myself. So I'm just floating this as an idea to see what people think.
Bumping this. I think it would be a great idea to include a spec with each exercise. Just include in the initial docs instructions on how to run clojure spec. Other than that, I think it would be quite obvious what the spec is describing.
Doing some post-v3 launch housekeeping, I took the liberty of closing many of the old issues that have either become obsolete or whose topics have been more recently discussed. This one, however, I agree is a great idea and would be willing to focus an effort to integrate spec.
