Wording and naming of kata snippets

[hobovsky]

Asked by @DonaldKellett here: #153 (review)

[...] may we rename the following terms?

• "Full test suite" --> "Submit tests"
• "Proposed solution" --> "Complete solution" / "Reference solution"

I agree that better wording could be used, but I have doubts:

"Submit tests" sounds off to me because it sound like activity (submit). But that's probably because my English sucks, so I will rely on you here :)

I do not like "complete solution" because... what would other solutions be? Incomplete?

I do not like "reference solution" because I do not know how to distinguish this term from the solution used by tests to generate expected answer.

Any hints? Maybe I'd need to check how the snippets are actually named in kata editor, and maybe stick to that?

[kazk]

I think we call them "submission test(s)" and "reference solution" at Qualified.

I do not know how to distinguish this term from the solution used by tests to generate expected answer.

Isn't it the same?

[hobovsky]

AFAIK the reference solution snippet is used only when kata or translation is being published to verify if it works, and is not accessible when user solution is submitted. Is it? Can random tests use this snippet to generate expected answer? Am I missing something, or need to get some sleep? :)

[kazk]

I see what you mean now. The one used in random tests is usually just copied from the author's solution because there's no other way. I'd call them both reference solution.

[JohanWiltink]

I have to absolutely disagree with @kazk here. ( Why does that feel like I'm sticking my neck in a noose? 😋 )

The author's solution and the one used in random tests serve different purposes, can be different, and probably should be different in many kata.

The author's solution, what I would call "example solution", is what goes in the "Complete solution" box in the kata editor. After solving, it's visible as the author's solution in the list of valid solutions. As such, it should exemplify any pointe the kata has, and it should first and foremost be readable.

The solution used to generate correct results in random tests I would call "reference solution". It should be fast, for maximum responsiveness of the kata's testing, and it might sacrifice readability for speed. It should still be as maintainable as can be achieved without sacrificing noticeable speed.

Advantages of having different implementations for example and reference solutions include

• both can achieve their own intended purpose better
• they can be tested against each other, minimising risk of incorrectness
• they might find different edge cases when running them against random inputs

[kazk]

Why does that feel like I'm sticking my neck in a noose?

I don't know why either, but you shouldn't feel that way. There's no point of working together if no one disagrees. Please always feel free to suggest improvements or explain anything we're missing.

I'm used to the term "reference solution" and haven't had issues because it's usually possible to know which one by context. But I can see it's confusing, so I'd welcome better terms that's more clear.

[JohanWiltink]

The terms mostly come up when discussing designing a kata, often with inexperienced authors (!). There is a definite need for separate terms, I am accustomed to using "example solution" and "references solution" as explained above, and I find they work well.

Also, consistency is good. Inexperienced kata authors often are overwhelmed with new and unfamiliar concepts already. If they're not confused by documentation, that can only help.

[Blind4Basics]

My 2 cents:

Through codwars iteself, I'm used to hear/see "reference solution" as the one being used in the test suite for the random tests (the wording seems pretty appropriate for this one, since it's the one enforcing the specifications). The "other one", I'd just call it "the author's/translator's solution", since it's actually just "a solution of one user", like any other user (almost... x) )

[kazk]

@ggorlen Any suggestions for better terms to distinguish the author's solution and the solution used to test against? I think at Qualified, we almost always have the same code for both. But the Codewars community raised some good points on the benefits of having different implementations. I think I've seen "working solution" somewhere for the author's solution, but I don't remember where.

[hobovsky]

Set up a pilot article on the new blog and let's run a survey among users :)

[ggorlen]

At Qualified, the reference solution (yep, we call it that) and the function used to validate random tests (has no name) are nearly always one and the same. It should be readable and fast enough to solve the task. I've never needed separate "readability" and "performance" versions, but a lot of migrated CW kata that we've used at Qualified often have reference solutions that are pretty much code golf, so I de-obfuscate these so our customers can understand them.

At CW, there's additionally the author's solution that, like B4B says, is pretty much just another user's solution. We don't have such a thing at Qualified and I'm not sure what to call it as long as it's clear that if a user wants to golf it as their personal submission, that's fine, but they should keep the "reference" solutions and anything that winds up in the testing code readable (I know we've stated this multiple times in the docs so far).