Using "Performance.now" is confusing

[davepullin]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/High_precision_timing

What specific section or headline is this issue about?

throughout the page

What information was incorrect, unhelpful, or incomplete?

Is it Performance or performance? You keep switching the capitalization!

What did you expect to see?

The same (and correct) capitalization is each place.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/api/performance_api/high_precision_timing
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/High_precision_timing
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/performance_api/high_precision_timing/index.md
• Last commit: 27c5383
• Document last modified: 2023-09-05T06:28:25.000Z

[bsmth]

Thanks for reporting @davepullin - the reason for capitalization is that the page is referring to a Web API - 'the Performance API' and when referencing the topic of performance, it follows normal sentence casing - 'For measuring performance...'.

All of the APIs follow this convention: https://developer.mozilla.org/en-US/docs/Web/API, for instance:

The File System API allows read, write and file management capabilities to access files on the device file system.

Does that make sense?

[davepullin]

Thanks. I should have been more explicit: I meant when referring to the actual javascript that needs to be written, not when 'performance' (english word) is used in a sentence. Specifically I need to know whether to code performance.now() or Performance.now() See the heading : Performance.now vs. Date.now <https://developer.mozilla.org/en-US/docs/Web/API/Performance/now#performance.now_vs._date.now> and the next heading performance.now specification changesperformance.now specification changes <https://developer.mozilla.org/en-US/docs/Web/API/Performance/now#performance.now_specification_changes> Obviously by now I found out by experimentation that it is the lower case version, which seems odd because I expected Performance to be a class. (or by analogy with Date), as so the fact that it is lowercase seems like a gratuitous trap, and perhaps should be highlighted? The code examples are correct. I should have believed them!

…

On Mon, Nov 13, 2023 at 8:52 AM Brian Thomas Smith ***@***.***> wrote: Thanks for reporting @davepullin <https://github.com/davepullin> - the reason for capitalization is that the page is referring to a Web API - 'the Performance API' and when referencing the topic of performance, it follows normal sentence casing - 'For measuring performance...'. All of the APIs follow this convention: https://developer.mozilla.org/en-US/docs/Web/API, for instance: The File System API allows read, write and file management capabilities to access files on the device file system. Does that make sense? — Reply to this email directly, view it on GitHub <#30238 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFIK6NIZZXIRPZT3BNI2HQ3YEIQYPAVCNFSM6AAAAAA7JFUXUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMBYGIYDIMJZGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[Josh-Cena]

Performance is indeed a class (an "interface", in IDL terms), but you don't use its constructor; instead, you use the exposed singleton instance called performance. When we say Performance.now(), we really mean the now() method of Performance instances, which you access via performance.now() in actual code. Web API docs don't differentiate between static and instance properties, but sometimes we write them in lowercase for pragmatic reasons. I'm okay to change the uppercase to lowercase on this page wherever applicable.

[davepullin]

Ok, thanks for the clarification.

…

On Mon, Nov 13, 2023, 12:06 PM Joshua Chen ***@***.***> wrote: Performance is indeed a class (an "interface", in IDL terms), but you don't use its constructor; instead, you use the exposed singleton instance called performance. When we say Performance.now(), we really mean the now() method of Performance instances, which you access via performance.now() in actual code. Web API docs don't differentiate between static and instance properties, but sometimes we write them in lowercase for pragmatic reasons. I'm okay to change the uppercase to lowercase on this page wherever applicable. — Reply to this email directly, view it on GitHub <#30238 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFIK6NIYYW3INEA5FUB2SCDYEJHRTAVCNFSM6AAAAAA7JFUXUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMBYGU4TSNBTHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[wbamberg]

It's hard to know what to do here. Our pretty consistent practice is to describe Web API methods in prose like InterfaceName.methodName(). This is confusing because for non-static methods you can't actually call it like that. And it is even more confusing in cases, like this one, where there is actually a global named interfaceName.

But that's our practice, and doing something different for just this one page feels wrong. And there's a good reason it is our practice, because writing something like "The methodName() method of the InterfaceName interface" gets really clunky.

[OnkarRuikar]

This is confusing because for non-static methods you can't actually call it like that. And it is even more confusing in cases, like this one, where there is actually a global named interfaceName.

I agree. Can we have . and # used as follows:

Number.EPSILON;  // static. When referenced using an interface
Number#toString();  // non-static. When referenced using an interface
myNumer.toString(); // non-static. Referenced using an instance

Performance.call();  //static
Performance#now(); // non-static
performance.now();  // non-static

The heading here could be Performance#now() vs Date.now().

For example

• Java documentation uses '#' to document class members.
• Ruby uses "::" for class methods, and "#" for instance methods.

[wbamberg]

This is a variant of https://discourse.mozilla.org/t/incorrect-titles-for-method-property-articles/31641 and https://github.com/orgs/mdn/discussions/248, which we fixed for titles, but not for in-prose references.

InterfaceName#methodName() has been proposed before, and has its detractors.

FWIW web.dev seems pretty settled on interfaceName.methodName().

[OnkarRuikar]

InterfaceName#methodName() has been proposed before, and has its detractors.

Ohh. Using other characters instead won't be welcomed either because they might have some meaning in JS.

FWIW web.dev seems pretty settled on interfaceName.methodName().

We could also ban InterfaceName.instanceMethod() and start using interfaceName.instanceMethod() everywhere. No need to change InterfaceName.staticMethod().