Method name of .toUpperCase

[paroche]

In the Data Types chapter, in the first section "Methods of primitives", it is written:

"For instance, there exists a method str.toUpperCase() that returns a capitalized string."

I would think the method name should just be ".toUpperCase()" without "str" (or else "String.prototype.toUpperCase()"). Or there's something I don't understand.

[iliakan]

That's just to show that it's a string method.

[paroche]

I did infer that. And soon after that statement you refer to the method name as "toUpperCase" without the "str.". But I think it would be clearer, and more accurate, to use just the actual method name from the start. One of the things I have found exceptionally good about your tutorials -- and I have been very impressed with them -- has been just that kind of explicit accuracy (I've also been impressed with the level of completeness and explanations of the underlying logic presented simply, clearly, and concisely). It makes it much easier to put things clearly in my mind than if I have to infer what you really mean or figure it out from context. That's how it is for me, anyway. But I think it could be the same way for a significant number of other people, whether they notice it or not.

[iliakan]

Could you please create a PR of the suggested fixes? Thanks!

[paroche]

To address the issue more generally, the earliest place in the tutorial where this type of notation is used I'm aware of is:
https://javascript.info/string

where under the "String length" subheading you have an alert:

"length is a property

People with a background in some other languages sometimes mistype by calling str.length() instead of just str.length. That doesn’t work.

Please note that str.length is a numeric property, not a function. There is no need to add parenthesis after it."

Perhaps somewhere in that alert you might also mention that in this tutorial you are using the shorthand "str" to refer to "a string" (though sometimes in the examples it is also a variable named "str"), so that, for instance, "str.property" means "a string followed by '.' followed by the property name (e.g. "length"). (I made a PR on that page giving an example of what I'm talking about).

The same considerations would apply to the use of "num" for "a number", as here:
https://javascript.info/number

Where "num" is used both as a shorthand for "a number" and as an actual variable name for a number.

And maybe for "obj" as well, which is occasionally used the same way:
https://javascript.info/keys-values-entries

Once one is clear on the conventions you're using it reads fine and I hardly notice, but the first times I encountered this type of usage I found it ambiguous and confusing. I think some explanation early on would help many first-time readers.

As mentioned before, I made a PR for https://javascript.info/string that addresses this issue, though I'm not sure if it's a final version.

Maybe after that is processed what changes may or may not be suggested for this page may be clearer.

[iliakan]

People are often reading the tutorial not in the straight order, skipping parts. They may skip such a note if only given once.

We can add an explanation everywhere: what a str or obj or num is.

[paroche]

Cool. Though I think a first-time explanation would probably also still be good.

…

-----Original Message----- From: Ilya Kantor <notifications@github.com> To: javascript-tutorial/en.javascript.info <en.javascript.info@noreply.github.com> Cc: paroche <sunmtnsft@aol.com>; Author <author@noreply.github.com> Sent: Mon, Aug 26, 2019 11:12 pm Subject: Re: [javascript-tutorial/en.javascript.info] Method name of .toUpperCase (#1220) People are often reading the tutorial not in the straight order, skipping parts. They may skip such a note if only given once.We can add an explanation everywhere: what a str or obj or num is.— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.