Authoring guidelines: translations

[hobovsky]

Prepare some kind of HOWTO about creating translations and translations best practices.

I have some idea in my head, but if anyone would like to share theirs, go ahead.

[Blind4Basics]

in unordered fashion:

• make preferably the description language agnostic (if the author is ok with te idea), but if not possible, don't forget to add the relevant codeblocks

wanted changes, compared to the original language:

• adding random tests (required)
• adding sample tests (required)
• clarifying the description if needed (only if the author is ok, if he's active)
• build a better organisation of the test suite

things where you need to "stay in line"

• respect the performances requirements of the original language. If needed decrease/increase the number of tests
• respect the perf of the original solution
• respect the overall setup of the initial solution (except for translations "from/to Java/C#" and alike where you adapt to what's the more loical
• all tests must be translated (unless irrelevant in the translated language)

things to be careful about: (these ones will have to be in "create a kata" too)

• write readable/maintainable code => golfed ref solutions like Giacommo cas used to do are to be avoided
• isolate completely ref and user code: when mutable data structures are used as input, either compute the expected result before sending the inputs to the user, or send copies to the user (deep copies if needed)
• respect the naming conventions of the translated language

[hobovsky]

Regarding your last paragraph, I was thinking on creating separate docs sections for:

• kata authoring guidelines which would explicitly mention only things related to kata idea, requirements, topics, and such,
• kata translation guidelines, which would contain majority of things mentioned by you: compatibility/differences with other versions, etc.
• kata "components" guidelines, which would include guidelines about writing specific snippets (description, full tests, sample tests, preloaded, ref solution). This part would be common to both translations and kata authoring, because both of them, well, have code :) It would be explicitly and visibly referenced by both of above sections.

Generally my idea would be to extract as much as possible to a common section about "creating a language version". "translating" howto and "kata creation" howto would have only guidelines related specifically to these concepts.

What do you think?

[Blind4Basics]

sounds good. As long as kata/translation guidelines have the link toward the last part. ;)

👍