docs: clarify suggestions for Difference of Squares

[dysolution]

The intent with this issue is to facilitate a discussion about proposed changes to the Difference of Squares mentor suggestion output. (A) pull request(s) can be submitted and linked to this issue to retain historical context.

This question was asked in the #track-go channel: https://exercism-team.slack.com/archives/CAS0EK88H/p1558543383014700

...and answered/discussed further here: https://exercism-team.slack.com/archives/CAS0EK88H/p1558543810015800

At the moment, the proposals for changes to the copy are:

These formulas are not as straightforward as they seem, and you aren't expected to create an efficient solution on your own. We encourage you to ask questions and do a little research. Finding the best algorithm is a key skill in software engineering.

and:

A loop or two will get this done brute force, but you can do better. Try looking at: _ ...and then have a couple of links to math pages.

and:

These formulas are absolutely as straightforward as they seem.

I would propose using these formulas are not obvious rather than these formulas are not as straightforward as they seem. While these algorithms may seem simple and elegant, many students (including myself) will not know/remember that they exist until prompted by a mentor to try searching for them:

func SquareOfSum(n int) int {
    sum := n * (n + 1) / 2
    return sum * sum
}

func SumOfSquares(n int) int {
    return (n * (n + 1) * (2*n + 1)) / 6
}

[bitfield]

This is where that hint came from (from exercism/problem-specifications#1421):

It's not that I'd reasonably expect anyone to remember the formulas from high school; we're learning programming here, not math. My point is that no one seems to think of looking for a formula in the first place. Maybe they think it would be cheating?

Perhaps a hint in the README along these lines would help:

Which is what we now have. From my own experience, it seems to have been hugely effective. Before the PR was merged to add this hint, 95% of solutions used loops. With the hint, only about 10% use loops.

I'm not saying that the wording of the hint can't be improved, of course. I'm just pointing out that it must be most of the way there, mustn't it?

[BethanyG]

@dysolution - I like your wording change. Agreed - we want some sort of prompt / nudge to the students to look for the formulas.

[BethanyG]

@bitfield - This is what I am seeing in the problem description, and what most students I see on the Python track implement:

The square of the sum of the first ten natural numbers is (1 + 2 + ... + 10)² = 55² = 3025.
The sum of the squares of the first ten natural numbers is 1² + 2² + ... + 10² = 385.

...and in fact, that's what I did when I solved the problem. I knew there might be a more efficient solution, but the one I made passed the tests, so I left it (sorry to say).

[bitfield]

we want some sort of prompt / nudge to the students to look for the formulas.

There were a few discussions about this at the time, as I recall, with a concern that we don't want to simply say "Google it", but nonetheless give the strongest possible hint that way, without actually saying it. The compromise arrived at was:

research is allowed, indeed, encouraged

I don't really know if we can put that any more plainly without giving it away. I'm not sure how much of an improvement this is:

We encourage you to ask questions and do a little research

Ask questions of whom? The mentor? That isn't really the avenue we want to guide them down if they're learning to do their own research, which all software engineers have to do. If it were:

We encourage you to do a little research

Then I'd be absolutely happy with that.

[bitfield]

If anything, I think removing this part would be actually be a more effective improvement:

The square of the sum of the first ten natural numbers is (1 + 2 + ... + 10)² = 55² = 3025.
The sum of the squares of the first ten natural numbers is 1² + 2² + ... + 10² = 385.

[BethanyG]

When I took Tim Roughgardens class on algorithms, he was forever repeating can we do better?. I liked that reminder to not stop. Maybe we do something similar to be a little more forceful?

A brute force approach might work here, but can you do better? We encourage you to do a little research.

[bitfield]

I like that very much! (I would write brute-force, with a hyphen.)

If it were left entirely to me, which would doubtless be a bad idea, I would say:

A brute-force approach might work here, but you must do better.

[dysolution]

Could I suggest something along these lines, unless we actually mean to gate approval based on whether the student finds and implements both algorithms?

A brute-force approach could work here, but if you're willing to do a little research elsewhere, there's a good chance you could do better. Are you up to the challenge?

The spirit I'm attempting here is to reward additional effort and exploration ("carrot") rather than imply that simple brute-forcing is a poor/inadequate solution ("stick").

[tehsphinx]

[do] we actually mean to gate approval based on whether the student finds and implements both algorithms?

I'd say if this is implemented in the go-analyzer for auto-approval, then yes. It seems to me it is the main point of the exercise to not use the loops but to search for the formulas. Would you agree on that?

Note: I also used the loops back then 😄 https://exercism.io/my/solutions/f61740e927ec4d05a8f3b43ff8f9dc31

[bitfield]

The spirit I'm attempting here is to reward additional effort and exploration ("carrot") rather than imply that simple brute-forcing is a poor/inadequate solution ("stick").

I commend you for it.

we actually mean to gate approval based on whether the student finds and implements both algorithms?

Yes, I would (and do) withhold approval from any exercise which uses a pathologically bad implementation (such as loops, for example). I wouldn't accept such a PR to a production codebase I was involved with, but it's not this specific mistake that I object to so much as a failure of engineering method. As Dijkstra reminds us, the competent programmer is fully aware of the strictly limited size of his own skull, and therefore we should not try to invent everything ourselves, but instead reflexively search for prior art. Until someone has learned to do this, they remain trapped inside their own head.

[dysolution]

I can see the value in gating approval this way. I'll admit that I've approved solutions that used loops, but only in cases where I've already given them the feedback about the algorithms and they submitted a further iteration retaining loops, which I take as a signal that they're not interested in that extra effort. I agree that it's a failure of engineering method. I have difficulty taking a hard line on this because it's a more general programming concern rather than something specific to Go, and I'm less inclined to halt their progress in the Go track for failing or refusing to find/implement these algorithms.

I sometimes wonder what to do when go-analyzer generates the same recommendation(s) for subsequent iterations and the student hasn't replied with any explanation (although many do explain): should I just "repeat myself" by preserving the analyzer's output verbatim, try asking them why they didn't address a recommendation, or be satisfied that I made the point and it's their loss to not have engaged with only one part of the provided mentoring?

[tehsphinx]

what to do when go-analyzer generates the same recommendation(s) for subsequent iterations
Good question!

Currently the analyzer comments are not used. Only approve_as_optimal is submitted, everything else goes to the mentor queue (https://exercism.io/mentor/analyses).

That question is still to be answered though. I think this will be handled by the website in the future. The analyzers will only analyze the solution without knowing about the context (previous iterations, etc.)

About handling this in an appropriate way as a human mentor, I agree with your description. I often approve but give a hint about improving the rest of the points I gave earlier or I explain e.g. golint/gofmt again in more detail.

[bitfield]

should I just "repeat myself" by preserving the analyzer's output verbatim, try asking them why they didn't address a recommendation, or be satisfied that I made the point and it's their loss to not have engaged with only one part of the provided mentoring?

All perfectly valid approaches, as far as I'm concerned. If they seem to have overlooked something completely, I'll remind them about it. If they're unwilling or argumentative, and I can't persuade them to make the changes, then we're into the 'mulish student knows best' scenario. Not to be confused with the 'exceptionally bright student needs to understand the reason for everything they're asked to do', which is different, and tractable.

I hate to spend time arguing with mulish students, because it takes time away from helping other students who have a more productive attitude. If the issue is a deal-breaker for me, I politely inform them that I've helped them as far as I can, and return the solution to the queue.