Discussion on: Do you think functional code readable ?

I am also interested in programming in a functional style, I care quite a lot about it so I want to contribute to the conversation.

Firstly, I want to say that I like your code, but also that the focus should be on how it can be changed to make it more readable for your colleagues.

A point that can be difficult for us to accept is that even though there are some general principles that can lead to programs being more or less readable (coupling, mutation, long functions, etc) readability can still be subjective: when we read a new piece of code, in order to have an easy time understanding the code, we must know what the little pieces do ("while" execute the block repeatedly, "range" returns an array, "if" does conditional execution, etc).

When we develop software with others, we should check first if your colleagues are familiar with or eager to embrace the concepts we want to introduce.

Then, when we program we keep in mind that the target audience is not the compiler (or interpreter), but other people and ask ourselves what we can do to make it easier for them to read the code. Thinking about our audience is not something we do only when programming but, actually, any time we communicate we choose which details to add and which details to leave out to correctly target the audience we have in mind.

To give you my personal experience reading this as an example, I can tell you that I know what the map() function does because I use it often and I even used Object.freeze(), so I know what it does, but I have not seen chain() before and so I don't know what it does. That means that there are parts of the code that I can read and parts of the code that are not easy for me to read and understand. Try to keep in mind that your readers will have some sort of experience like this when reading the code and try to imagine what they will feel and think when you are writing it.

I won't claim to know the solution here. I don't even have much experience working with other programmers myself, but here's a couple of ideas that I think may help.

• There is a cost to novelty. For example, one reason why we break down large functions into smaller ones is that they would be too complex otherwise. When introducing new functional programming concepts to the code base, maybe you can think of them as being especially costly and that the code around them should be especially clear, to make their usage more obvious (so as an example, maybe don't chain too many unfamiliar functions, but, instead, break down the chain with multiple variable assignments with friendly names).
• Document the things that may be unfamiliar to your readers. You can add a brief summary to each of your functions saying what the function does, at a high level. Here is an example:

/* Takes the piece from position `move` and moves
it into the hole. Modifies the game board in-place. */
process_move(...) {...}

• Lastly, a few unit-tests could make a big difference in helping others understand the code. Consider adding a few tests showing what the outputs of functions should be, given some simple example inputs.

// this would be somewhere in the body of a unit test function
assertEqual(get_piece([
  [♔, ♙],
  [♙,  ],
], 0, 0), ♔)

Vectors are Cool

There's one last thing I want to add. I don't think it would help with readability in your case, but I want to mention it just because I love vectors. In your code, you have some parts that operate on components of vectors like this.

const to_move_x = board.hole_x + move[0];
const to_move_y = board.hole_y + move[1];

Each of the two lines here does the same operation, but for each component. This could be written more briefly with vectors.

const to_move = Vector.add(board.hole, move)

An example of a vector class implementation can be found here on this gist.