Grains: clarify what "total grains" means

[bhagerty]

In the Grains exercise, the specification says code should show "the total number of grains on the chessboard." This is not entirely clear.

I read this to mean "the total number of grains on the chessboard, assuming it is full." And code returning this number passes the tests (at least in Python).

But from the community solutions, it's clear many people read this to mean "the total number of grains on the chessboard up to and including square X," where X is a number between 1 and 64.

I suggest clarifying the instructions to clearly reflect whether total grains means (1) the grains on a completed 64-square chess board, or (2) the grains up to and including an arbitrary square on the chess board.

[NobbZ]

The exercise has 2 parts.

1. Given a number from 1 through 64, calculate the grains on the given field, other fields not included.
2. Called without arguments, return the total number of grains on the chessboard. As we do not receive any argument here, we ca not calculate "total for n fields covered, but have to decide between the 65 possible ways to fill the board, where putting grains on all 64 fields is the most obvious interpretation for "total". And also the one expected from the canonical data

I'd be interested in seeing the solutions that calculate for arbitrary count of filled fields.

[siebenschlaefer]

@NobbZ I've seen a few those solutions on the C++ track where total() takes a parameter with a default value of 64 and the function then returns the sum of grains up to that field. (But that always felt like the student didn't like a function that returns a fixed value or they wanted to "up the game".)

[ErikSchierboom]

There are 64 squares on a chessboard (where square 1 has one grain, square 2 has two grains, and so on).

Write code that shows:

how many grains were on a given square, and
the total number of grains on the chessboard

It might be that I just know how to interpret this, but to me this description states that:

• Each square has a number of grains
• There are 64 squares

I'm not sure that ", assuming it is full" adds anything, because of the first line implying that each square has grains.
We're of course open to improvements, I just don't think the suggested changes offer much value.
But others might disagree.

p.s. taking a parameter for total does not offer much value I think. For many languages, the value of the total property is that it lies outside the range of a 32-bit integer.

[NobbZ]

@siebenschlaefer Yes, I never liked that many tracks force to write a function where more appropriate tools like a const would have been available, but thats the world we are living in…

[bhagerty]

Thanks for all of these comments. To be clear, I am saying that there are, in fact—as shown by the reactions of other human beings—different ways to read the problem specification. I'm making a claim about the world, supported by evidence. People are, in fact, reading the problem statement differently, which shows that clarification would be helpful.

It seems like the commenters here read this problem statement as I do, to mean: Assuming every square is full, return the total number of grains. And I agree, that's the most-obvious reading.

But the evidence shows that this is not how everyone reads it. I saw many community solutions that reflected the second reading of the problem provided in my original comment—that is, return the total number of grains up to square X of an arbitrary number. And that is not a manifestly crazy reading of the problem. It's actually a reasonable, defensible inference from the fact that the first part of the statement says to calculate the number of grains in an arbitrary square. If I'm being asked to calculate grains in an arbitrary square, maybe I'm also being asked to calculate grains up to that arbitrary square, and maybe the problem writer was a little sloppy.

This may not be the most-obvious reading of the specification. Again, it's not how I read it. But it's how other people read it. So adding "assuming it is full" does add something: it clarifies something that, from the evidence, is not clear. It is hard for me to understand why anyone would object to a clarification that (1) real-world evidence shows is needed by some people, and (2) does not make the problem less clear.

In short, "It's clear to me" is not the same thing as "it is in fact clear," and it doesn't actually contradict evidence showing "it is not clear to other people."

[ErikSchierboom]

It is hard for me to understand why anyone would object to a clarification that (1) real-world evidence shows is needed by some people, and (2) does not make the problem less clear.

I don't object to the improvement, I'm just not entirely sure I like the "assuming it is full" Maybe there's an alternative way to phrase this that makes it more clear?

It is hard for me to understand why anyone would object to a clarification that (1) real-world evidence shows is needed by some people

We likely have different experiences. I've not yet come across people making this mistake, but that may just be a coincidence.

[kotp]

"Assuming it is full" also had a weird tinge to me. The fact is that it does not have to be full in order for it to have the total at the point of where that should be. Indeed the board that the grains are on may have very large squares. Indeed, the first 2 squares are unlikely to be full at all. The fact that the problem is a doubling of the grains at each location, and the statement that there are 64 locations, does not suggest that anything is full, only that there is a total.

Perhaps "total grains on the board" makes it clear, without inferring some capacity potential of the board upon which it is on.

[bhagerty]

Thanks. I am not married to "assuming it is full." That was meant to convey the concept. Other options:

• "the total number of grains on the chessboard after placing grains on every square."
• "the total number of grains on the chessboard after grains have been placed on every square."
• "the total number of grains on the chessboard, assuming every square has the required number of grains."
• "the total number of grains on the chessboard once the process of filling squares is complete."

Other options are also possible. Again, I'm not married to "full," I just want to address the misunderstanding I saw reflected in community solutions to this problem.

[junedev]

I am pro clarification and I like this one from above:

"the total number of grains on the chessboard after placing grains on every square."

[SleeplessByte]

I also am in favour of the clarification @junedev picked. Thanks @bhagerty!

[iHiD]

I am saying that there are, in fact—as shown by the reactions of other human beings—different ways to read the problem specification. I'm making a claim about the world, supported by evidence. People are, in fact, reading the problem statement differently, which shows that clarification would be helpful.

I try to stay out of these discussions, but I felt like such a strong statement needed addressing, as I don't believe it to be true. While I don't dispute that some people may be misled by this, I don't believe we have evidence to suggest that they are. We have a correlation between that statement in the instructions and a plethora of community solutions that take a param for total. But I do not believe we have any evidence that the README is a causation for the solutions.

Looking back in time, the version of the exercise that the top Python community solutions was solving actively required a parameter to be passed, and that the result should be calculated based on it (this was changed here:
https://github.com/exercism/python/pull/1794/files). This is much more likely to be why the community solutions show this. Looking at the most recent community solutions for Python, it's extremely rare for people to require an argument.

I'd postulate when people do require an argument, they're probably extending the exercise for themselves. That postulation may be wrong and they may indeed be confused, but I don't believe we have evidence to show that.

---

My stance on the actual issue is that more clarity is always better, so if changing that statement makes the exercise clearer, then I'm for it, but I don't believe we have any evidence that it's necessary, and thanks @bhagerty from wanting to improve things!

[SaschaMann]

These suggestions would be a breaking change to the exercise. On the Julia track, we interpret the task as

Calculate the total number of grains after square square.

where square is the argument. In other words, the total number of grains on the board after square squares have been filled. [Example solution]

This covers the case where all squares have been filled but isn't limited to that case.

I feel like there's an agreement in this issue that the current wording can be interpreted differently and evidently maintainers have done so in the past, too. Therefore I am against an Exercism-wide change that forces one interpretation as it would needlessly break implementations of the exercise. Instead, tracks should be encouraged to clarify this locally based on their test suite.

[bhagerty]

So this is fascinating. The entire Julia track interprets the problem differently from how most of the posters here (including me) interpret it. Surely this is evidence that the problem statement is not clear, if any more is needed.

I don't, however, think it makes sense to leave it unclear to avoid "breaking" the Julia track. If the idea is that these exercises are language-agnostic, then they should be clear across every language, not be susceptible of different interpretations in different language tracks.

I actually think the Julia-track interpretation of the problem—give us total grains up to square X—is more interesting than the other interpretation—give us total grains if every square has grains.

I don't really know how best to resolve this. I only think that it should be resolved (otherwise the problem is unclear, and its use is not language-agnostic), and that the debate over whether the problem statement is unclear should be considered closed. The problem statement is unclear to a non-trivial number of people.

Though I appreciate @iHiD clarifying that what I saw as evidence of unclarity could have been evidence of a change in the problem statement. I wasn't aware of that change. That makes sense. So there may be less evidence than I thought, because I was misinterpreting the evidence based on a faulty supposition (that the solutions I saw answered the current problem statement). I still think clarification is needed, though, especially in light of @SaschaMann's comment.

[junedev]

@SaschaMann To clarify, does that mean you would veto the discussed clarification PR if someone would create it?

[SaschaMann]

I don't, however, think it makes sense to leave it unclear to avoid "breaking" the Julia track. If the idea is that these exercises are language-agnostic, then they should be clear across every language, not be susceptible of different interpretations in different language tracks.

IMO exercises being language-agnostic doesn't require that they're identical across languages. Each track can use the shared spec as a foundation to build an interesting exercise that makes sense in the language. To me it merely means that ideally they're written in a way that enables them to work well on the largest numbers of tracks (even if that requires them to be a bit more vague) and that they should avoid language-specific concepts or jargon unless strictly required.

I also don't think it should be left unclear, I just don't think that prob-specs is where this change needs to happen as it would restrict the exercise pointlessly. It should happen in the tracks based on their take on the common data of the exercise.

I want to point out that this conflict between people who just want to auto-generate exercises blindly based on the shared prob-spec, therefore requiring a more precise and exhaustive description and set of tests, and people who take prob-spec as a pool of interesting exercises that can and should be adapted by the maintainers has lead to endless discussions in the past. I'm very much in the latter camp; the vagueness is (to some extent) a feature of prob-specs.

I actually think the Julia-track interpretation of the problem—give us total grains up to square X—is more interesting than the other interpretation—give us total grains if every square has grains.

I agree. I'd like to claim that was intended but I think we just copied that from Python's implementation before it was changed.

@SaschaMann To clarify, does that mean you would veto the discussed clarification PR if someone would create it?

Yes.

I'd be happy with a change similar to #1856, though, or a comment in the canonical data that points out that maintainers have to decide what approach they prefer. There is a dicussion somewhere in an Exercism repo on how to handle optional parts in the description that become necessary due to implementing certain cases, which could also solve this. However, I can't find that. #1749