Proposal: Add canonical data "identifier" field to separate concern from test "description"

[bencoman]

[Edit:] Some languages don't individually identify tests and use the canonical data "description" field to generate comments into their tests code. Other languages individually identify tests, but all that is available for generating a test-name identifiers is the "description" field. This results in some extremely long test-method-names. e.g. For robot-simulator Pharo has...
test18_WhereRTurnRightLTurnLeftAndAAdvanceTheRobotCanFollowASeriesOfInstructionsAndEndUpWithTheCorrectPositionAndDirectionInstructionsToMoveEastAndNorth

Can an optional identifier field be introduced for cases where the description doesn't make a good identifier?

For example, for the Bowling exercise...

{
    "description": "Bonus rolls for a strike in the last frame must be rolled before score can be calculated",
    "property": "score",
    "input": {
      "previousRolls": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10]
}

generating tests for different tracks produces the following...

CSharp:
public void Bonus_rolls_for_a_strike_in_the_last_frame_must_be_rolled_before_score_can_be_calculated()
https://github.com/exercism/csharp/blob/master/exercises/bowling/BowlingTest.cs#L250

Delphi:
procedure BowlingTests.Bonus_rolls_for_a_strike_in_the_last_frame_must_be_rolled_before_score_can_be_calculated;
https://github.com/exercism/delphi/blob/master/exercises/bowling/uBowlingTests.pas#L324

FSharp:
let ``Both bonus rolls for a strike in the last frame must be rolled before score can be calculated`` () =
https://github.com/exercism/fsharp/blob/master/exercises/bowling/BowlingTest.fs#L177

Adding a optional identifier like below would be useful.

{
    "identifier": "roll_bonus_balls_before_scoring"
    "description": "Bonus rolls for a strike in the last frame must be rolled before score can be calculated",
    "property": "score",
    "input": {
      "previousRolls": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10]
}

[bencoman]

Further to this, it seems that description ends up trying to serve two purposes:

• method comment
• method name

and ends up serving neither well. It constrains the length of method comments and encourages too-long method names.

[bencoman]

Reading more about the schema... https://github.com/exercism/problem-specifications/blob/master/canonical-schema.json

and also that "Comments ... can be used almost anywhere" https://github.com/exercism/problem-specifications/blob/master/README.md#test-data-format-canonical-datajson

to fit current schema perhaps it would be reasonable for me to shorten the description like this...

{
    "description": "roll bonus balls before scoring"
    "comments": 
           [ "Bonus balls for a strike in the last frame must be ",
           , "rolled before score can be calculated" ],
    "property": "score",
    "input": {
      "previousRolls": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10]
}

[EDIT:] In practice this seems to be turning out to be a bad idea. I now expect there will be a lot of push back trying to slim down the descriptions, and conversation will just bog down going in circles trying to reconcile dual purposes (description and identifier) from the one field. This PR for example... #1525

[rpottsoh]

Using your example as an example one might consider it easier to just adjust the ordering in the sentence, to simplify it and thus shorten it:

"description": "Score calculated after bonus rolled strike in last frame"

This new description retains the meaning of the original description. There is no guarantee that the comments will translate into a track's test suite. The comments are there for the maintainers benefit in building the test suite for their track.

Instead of reworking the schema for the canonical data I think the first step ought to be seeing if it is possible to refactor the "offensive" descriptions to be less offensive, to be more concise but without making the language too sophisticated. For many people English is not their first language, so one has to be careful to not make the language too efficient so as to be difficult for a non-native English speakers to understand easily.

Don't take what I have said as meaning I am against changing the schema, quite the opposite. I just don't think changing the schema is necessarily the solution we need to rush too.

[ErikSchierboom]

Instead of reworking the schema for the canonical data I think the first step ought to be seeing if it is possible to refactor the "offensive" descriptions to be less offensive, to be more concise but without making the language too sophisticated.

This would also be my preference. The example you presented (bowling), is one of the test suites with the longest descriptions. So maybe if we can shorten those, the problem goes away?

[macta]

We can certainly see if we can improve the descriptions to generate better. Also worth noting that some test cases have nested descriptions - e.g. and often these repeat what the parent description say vs. refining it. Triangle is an example of this and it should be corrected (along with checking all the other sub-cased examples).

(the geek in me did think it would be fun to take a munged description and hit some web service to summarise it - but that's where the angel on my other shoulder shouts....stoppppp)