Docs: The % (Remainder) operator is named incorrectly in the docs

[aaronfranke]

https://github.com/dotnet/docs/blob/master/docs/csharp/language-reference/operators/modulus-operator.md

https://github.com/dotnet/docs/blob/master/docs/csharp/language-reference/operators/index.md

This operator is named incorrectly in the documentation. It should be "Remainder" not "Modulus".

In C#, the functionality of the % operator is the Remainder function. The Remainder function returns a value that is the remainder after standard division. For example, 10 % 3 is 1, and this is true for both Remainder and Modulus.

The difference between these two is with negative numbers.

• The standard integer division -10 / 3 is -3 so the Remainder can be found with -10 - (-3)*3 which is -1. Remainder of a and b returns a value on the range (-b, b) (both exclusive).

• However, the Modulus function of -10 and 3 would return 2. Modulus satisfies a similar formula but with floored division. Floor division of -10 and 3 is -4 instead of -3, and -10 - (-4)*3 is 2. Modulus of a and b returns a value on the range [0, b) (0 inclusive, b exclusive).

• C# does not have operators for Modulus or floored division, only Remainder and standard division. The docs should reflect this, so all documentation for % should be renamed to Remainder.

Here's Eric Lippert's thoughts on the issue: https://blogs.msdn.microsoft.com/ericlippert/2011/12/05/whats-the-difference-remainder-vs-modulus/

It's easy to see why this confusion exists, as Remainder and Modulus are equivalent functions for positive numbers. But they are not the same operations. Describing % as Modulus leads to confusion: https://stackoverflow.com/questions/10065080/mod-explanation

[pkulikov]

@aaronfranke you are right, thank you for reporing the issue.While the operator page itself doesn't mention modulus, the URL address might be misleading (I would rename the filename). The description in the operators table should be fixed. I am willing to update both pages to add clarifications.

[svick]

I'm not sure the terminology is as clear as you imply:

• Eric Lippert is very careful in his article to use the term canonical modulus, which is not the same as just "modulus".
• The Wikipedia article about this issue, Modulo operation says "modulus" is a synonym of "modulo", which covers all the options. And it describes the two options as "remainder of truncated division" and "remainder of Euclidean division".

Do you have a source that actually uses the terminology that you suggest? Otherwise, I think changing the name is not really important and won't solve any confusion. If there is confusion, the description of the operator should be made clearer instead.

[pkulikov]

It's confusing now, because both names are used in docs. We should select only one.

I would also update the article about division with the remark about rounding towards zero and cross-reference division and remainder articles.

[aaronfranke]

Regardless of what the mathematical definition is, nearly every programming language defines Remainder and Modulus this way. Plus we don't have to mention the term "Modulus" unless we want to add a clarification like "The Remainder operator is not to be confused with canonical Modulus"

[pkulikov]

I think both @aaronfranke and @svick are right.

While for mathematicians, modulus is clear and coincides with the canonical modulus term, and they build the whole world of it, in computing, people like to argue about the definition of modulus as the Wiki article referenced by @svick demonstrates. The dangerous part with using modulus term is that some mathematicians might be confident in what % modulus operator does and be just wrong at the same time.

Remainder definition depends on the answer to the question: What kind of division do we talk about? I hope when one sees remainder term, one is more aware about the questions that should appear in one's head.

To summarize, in context of programming languages, both modulus and remainder terms might have various definitions for themselves. That implies:

• it's better to use only one term to reduce the amount of confusion
• the chosen term should be clarified: what definition is in use by the language.

As for the term to select, I suggest to use remainder as

• it's already used in the docs with modulus injections here and where
• the last sentence from the referenced article of Eric Lippert is The % operator does not give the canonical modulus, it gives the remainder.

To make definitions more clear, the following should be done:

• article on division should have a remark about rounding to zero for the integer arithmetic
• article on remainder should reference the division article and have a remark what happens when operands have different signs (not demonstrate that only by the example, as it is now)
• overview page should mention only remainder term.

@svick @aaronfranke what do you think? If that sounds like a plan, I'll make the PR for that.

[BillWagner]

@aaronfranke @pkulikov @svick Cool discussion

I checked the official ECMA spec proposal for C# 5, and the draft C# 6.0 specification. Both use Remainder exclusively.

I propose we adopt the same in docs: remainder is the preferred term.

There are two locations where this could be problematic, or needs further explanation:

1. The IL operator is Op_modulus (noted in operator overloading): In this instance, we should continue to use Op_modulus as the correct term.
2. The System.Decimal type contains a method named Remainder and a topic for the Modulus operator. Both perform the same operations. I propose changing the title of the Modulus operator to Remainder operator.

/cc @madsTorgersen for a quick review.

@aaronfranke This would involve changing file names. Whenever we change a file name, we update the .openpublishing.redirection.json file in the root directory to ensure incoming links work and search results redirect correctly. Internal links are all updated to the new file. Let me know if you have any questions.

[svick]

@pkulikov @BillWagner Consistently using "remainder" sounds good to me.

[aaronfranke]

Thanks for the great work everyone! :tada: