moveToSquare looks like hiding a concept

[flavius]

Lines like

$player->moveToSquare (1, 2);

feel like they're hiding a concept which exists in the business, but is not modelled in the code.

1 and 2 are magic constants. They are map coordinates and there are restrictions for them: they are pairs of values 1,2 or 3.

Make this concept from the business domain official also in the code. Make a new value object which can be created like this new MapCoordinate(1, 2) and make moveToSquare accept only an instance of MapCoordinate.

The line from the test will be more expressive:

$player->moveToSquare (new MapCoordinate(1, 2));

Now we read straight from the code "the story" behind this line: a player moves to square at map coordinate (1,2).

Code is not just code, the code tells a story!

[flavius]

This being said, this line of story is an unnatural wording a player moves to square at map coordinate (1,2)

A natural wording could be player puts his symbol at map coordinate (1,2).

"move" is not what you want to say, because it's not like a player is at a coordinate, and then he moves from that coordinate to a new coordinate.

And so, the method name could be putSymbol. Or anything else which reads naturally.

You want code to be read naturally, like a story.

[wolfenste]

I will use putMark instead of putSymbol because I do not have the 'Symbol' word in my documentation .md file. I used 'mark' there. I hope it is a good decision.

[flavius]

I agree in this case.

In a different situation, if you really missed a terminology in the documentation, you can also edit that documentation - it's not set in stone.