Problem-specifications: minesweeper tests do not contain border

[BartMassey]

In the description of the minesweeper problem, the minefield is shown as being surrounded by border characters. The test cases have no borders. Borders make the problem a bit easier by obviating the need for clipping. Should fix either the tests or the description.

[petertseng]

this issue needs to be moved to problem-specifications. it now has been.

[sprinkle24]

I can work on this

[yawpitch]

_How_ does the border make the problem easier? The function receives a transmitted representation of the play state of the game ... _why_ would you want to include the border in that play state? It's either unchanging, in which case you're just transmitting redundant information, or it's potentially malformed on its own, and now you've got to parse whether or not the border is correctly formed.

[BartMassey]

Just means that you can avoid doing a bunch of bounds checks on array references without going off the edges of the array. It's not a big deal one way or the other, as long as it's consistent.

[NobbZ]

But if you include the border, then usual arithmetic to map 2 coordinates in a single index for a flattened down array wouldn't work anymore properly.

In my opinion including the border would makes things harder rather than easier.

[BartMassey]

The arithmetic still works fine, you just have to run loops etc from 1..n-1 rather than 0..n. Without sentinels for the borders you will still have to account for *(a + i * n + j - 1) not necessarily being the cell to the left of *(a + i * n + j) because of wraparound.

That said, I'm good either way. Just make the description agree with the API one way or the other.

[NobbZ]

I'm not sure where you think there is a mismatch? The border in the example is to make it easier for the human to understand the example.

The JSON though is to be parsed by maintainers and test-generators, which again may choose to parse [" ", " * ", " "] into {3,3," * "} or even {3,3,[empty, empty, empty, empty, mine, empty, empty, empty, empty]}.

[yawpitch]

I'm not sure where you think there is a mismatch? The border in the example is to make it easier for the human to understand the example.

There is a mismatch in that the description.md _implies_ that borders will be in the data the student has to work with. Since the student never sees the JSON that's a reasonable inference.

This _could_ be resolved by incorporating some text in the description.md that clearly states that the borders are for display purposes only and will _not_ be in the test data.

[NobbZ]

So if we left away the border how would you show the difference of the two examples?

*  

and

*    

Hin: The upper board is 3x3, the bottom one is 4x3.

We do not have any other way to properly display the dimension in the markdown but the border, which is visually clear or mentioning in a side note that the board is 3x3, which one can easily oversee.

In my eye its the job of the maintainer to properly communicate the input format via tests, HINTS.md or stub code/comments.

[sshine]

So perhaps rather than add borders to the expected output of the functions, this is an indicator that the ASCII-based illustrations we use in README.md get mixed up with the input data; this is, I believe, not the first exercise for which this interpretation has occurred.

Perhaps we should rather seek to draw the border using something other than ASCII characters.

This would improve the aesthetics of those exercise descriptions that need illustrations, too.

[yawpitch]

@sshine how would you propose we draw that border? Would we put a border around _all_ <code> elements? If not we'd need to extend markdown processing to allow for some sort of "this is a figure that needs borders" tag.

Personally I'd just update the copy to state that the border is for demo purposes only... I do not believe the current disconnect between the description and the test data has led to substantial confusion, since the test data takes de facto precedence.

[sshine]

@yawpitch: Yes, drawing a border around <code> segments could be one way to do it.

Alternatively, one could remove the ASCII border in the description.

Or use ·s to denote spaces like in diamond: #344 and #347 discuss a very similar border. I seem to recall someone misunderstanding · as meaning something other than a space in the context of a PR, so perhaps a common observation is that if the example / sample / visualisation in the description deviates too much from the actual data type for a given track implementation of an exercise, misunderstandings will occur.

Rendering sample inputs in the exercise description is tangentially related to exercism/exercism#5033.

[yawpitch]

@sshine and @BartMassey would #1602 sufficiently clarify the description.md?

The . replacement from diamond is, I believe, quite sufficient in this case as well.

[sshine]

Diamond uses · and not ..

Other than that, I don't have a strong opinion.

[yawpitch]

·

That is _so_ not obvious in vi ... I'll fix that.