Create mentoring.md for grains exercice in cpp

[CornierQuentin]

Creating the guide for the solution of the grains exercise in cpp. Offering an imperative and a recursive solution for the first function and explaining how to do correctly the second function.

[CornierQuentin]

I've removed "cleaner", changed "indice" to "index" and added the direct method. Hope you will like the changes, don't hesitate to ask me for more changes if you need. I also wanted to ask you if this is a good things to add such documentation and if you like me to add some more ?

[siebenschlaefer]

Thank you!

The whole documents sounds like its target audience are "students", e.g. it explains bitwise left-shifting with an example. But these mentoring notes are for "mentors" who (ideally) should already have solved the exercise, understand the assignment and solutions, and want to help others improve their solutions.

Mentoring notes typically contain (1) reasonable solutions, (2) common issues that often occur in solutions (i.e. subtle errors or code smells that a mentor might want to look out for), (3) common suggestions that often can improve solutions, and (4) talking points that repeatedly come up in these discussions. (see https://exercism.org/docs/building/product/mentoring-notes)

For example: I've seen many solutions that implement both functions by calling std::pow(). That works for square() (although it involves floating point arithmetic) but (depending on the exact implementation) not always for total() (the conversion from a floating point value to an integer invokes UB if the integer type cannot represent the value after the truncation of the fractional part). There are solutions that pass the tests but are not valid C++ (e.g. https://exercism.org/tracks/cpp/exercises/grains/solutions/Uberlicious).
Or another issue that I've seen from time to time is using the wrong integer type, e.g. unsigned long or (signed) long long. That can work and pass the tests but only on specific platforms or it might have the wrong semantics. As for talking points: I've had a few discussions with students about performance, and what is the fastest implementation.

If you want to explain the exercise to a "student" you might want to write "approaches" instead. (see https://exercism.org/docs/building/tracks/approaches). Typically they explain language constructs like the operator << or the general idea of a bitwise left-shift. They are also more visible because we have much more "students" than "mentors, you will get a bigger audience.

Hope you will like the changes, don't hesitate to ask me for more changes if you need.

Do you mind adding an implementation with a direct computation for the second function, too? What are issues that you've seen in multiple solutions and that should be addressed by the student? What are typical suggestions that helped the students improve their solution? Are there any talking points, things that came up a few times in your discussion?

And a few tiny nitpicks:

• You put a space before each colon. IIRC that's correct in French, but in English there's no such space before colons, exclamation marks, question marks, ...
• You might want to use single(!) backticks around code fragments (such as variable names or keywords like for) that are embedded in a line. The three backticks are for multiple-line code snippets.

I also wanted to ask you if this is a good things to add such documentation and if you like me to add some more ?

We love contributions, especially documentation. If you need any feedback, input, or help feel free to reach out to me or @vaeng on the forum or on Discord.

[CornierQuentin]

I've done the changes you've asked for. I wasn't sure about the direct implementation because I often see direct implementation with ULLONG_MAX however it's, in my opinion, like cheating and hard coding the solution just a bit cleaner. So, with this point of view, I also add it to the common issues. I quite new to exercism and I wasn't sure were to write this doc, I think I will, after finishing this one, make more appoaches doc because I'm not quite sure I have the level to explain to mentors directly.

[siebenschlaefer]

@IsaacG Thanks for reminding me. This got lost in my inbox.

I have to admit I'm unsure about this. Do we really want to encourage students to solve this exercise naively, with loops that repeatedly multiply and/or add? Sure, such a solution is not objectively wrong, but in my opinion it does not go beyond translating the instructions directly into C++, there's no discovery or learning experience.

IMHO this exercise aims at a more elaborate or efficient approach, it wants the students to discover the underlying mathematical principles and that the number of grains on a square and on the whole board can be calculated directly, either with exponentiation or with bitwise operations. IIRC back in Exercism-v2 when exercises had tags this was tagged with "bit operations".

I'd appreciate if some of the other experienced mentors or maintainers would weigh in.

[vaeng]

I would also go for the "bit" direction as it is the most straightforward way to solve an exercise based on 2^x questions. I might be heavily biased though, as I am wired to binary and haven't been a novice student in a while.

[IsaacG]

I have to admit I'm unsure about this. Do we really want to encourage students to solve this exercise naively, with loops that repeatedly multiply and/or add? Sure, such a solution is not objectively wrong, but in my opinion it does not go beyond translating the instructions directly into C++, there's no discovery or learning experience.

I don't think we want to encourage students to solve things in any particular direction. We want to encourage them to write code, think and explore. The loop approach isn't ideal but it's not wrong. It's good practice either way. I would encourage students to examine the numbers and look for patterns and think about ways to leverage them.

IMHO this exercise aims at a more elaborate or efficient approach, it wants the students to discover the underlying mathematical principles and that the number of grains on a square and on the whole board can be calculated directly, either with exponentiation or with bitwise operations. IIRC back in Exercism-v2 when exercises had tags this was tagged with "bit operations".

Exercism is about programming, not math and finding closed formula solutions for problems. I've seen people solve sum-of-multiples and multiples-of-sums using closed forumulas but I certainly would not expect that of most students. Unless the instructions explicitly call out that students should look for bitwise approaches, I wouldn't push for that very much. On the Python track, I never suggest replacing exponents with bitwise shifts.

[siebenschlaefer]

I don't think we want to encourage students to solve things in any particular direction.

Are you sure about that? I've seen quite a few mentoring notes that said something like "try to nudge the student towards this ..." or "suggest that they ..." or "direct them towards ...".

[...] I would encourage students to examine the numbers and look for patterns and think about ways to leverage them.

So you do want to guide them towards a less naive solution? I'm with you on that.

Unless the instructions explicitly call out that students should look for bitwise approaches, I wouldn't push for that very much. On the Python track, I never suggest replacing exponents with bitwise shifts.

As I wrote earlier, IMHO exponentiation is fine, too. (But in C++ you have to be careful when using pow() in the function total(), I've seen a lot of solutions with undefined behavior.)

[IsaacG]

I don't think we want to encourage students to solve things in any particular direction.

Are you sure about that? I've seen quite a few mentoring notes that said something like "try to nudge the student towards this ..." or "suggest that they ..." or "direct them towards ...".

I'm sure that's what I think. That doesn't mean all the mentoring notes align with what I think we want.

So you do want to guide them towards a less naive solution?

Yes. I want to guide them to explore and think about less naive solutions. Without being prescriptive and telling them they need to implement any specific solution. If they recognize the pattern and opt not to use it in their solution, I think that's entirely fine.