Establish conventions for adding window./self. prefix

[Josh-Cena]

This comes from mdn/content#27666. The question is: when referring to a global variable, do we prefix it with the global object?

• Pros: adding it makes it more obvious/beginner-friendly;
• Cons: not adding it is less verbose and can be potentially executed in other non-window contexts.

My personal suggestion is we should avoid window./self. prefixes as much as possible, to ensure it can always be cross-platform.

However, do we have different preferences for different properties?

• Global interfaces seems the least likely to be prefixed (window.AudioContext).
• Global functions often are (window.requestAnimationFrame()) and is a big source of inconsistency.
• Global properties often are, but differs between types (window.isSecureContext, window.crypto). For exmaple, window.localStorage and window.console are probably bizarre, but it’s more bizarre to know that we ALWAYS write window.crypto and window.indexedDB with the prefix, which I don't think is a good practice.

Here is my proposed standard:

• No prefix if available in non-window contexts (worker etc.)
• No prefix if interface (uppercase)
• No prefix if global singleton of an interface (e.g. localStorage, crypto, including console)
• Otherwise: prefix (scrollTo(), innerWidth, … looks like it would also include alert()/prompt()?)

If it helps, here's a list of window. prefixed globals throughout our code (some may be in macro calls, I just used a regex to match all content):

addEventListener 259
crypto 95
requestAnimationFrame 87
indexedDB 66
open 58
sharedStorage 54
location 40
innerWidth 34
innerHeight 34
getSelection 33
matchMedia 32
navigator 31
speechSynthesis 28
alert 26
screen 25
getComputedStyle 24
postMessage 23
screenLeft 22
onload 19
prompt 19
launchQueue 19
screenTop 18
cancelAnimationFrame 17
getScreenDetails 17
opener 17
devicePixelRatio 13
queryLocalFonts 13
removeEventListener 12
showOpenFilePicker 11
confirm 11
top 11
frames 11
window 10
self 10
scrollTo 10
documentPictureInPicture 10
URL 10
x 9
y 9
localStorage 9
eval 8
resizeTo 8
resizeBy 8
CSS 8
outerHeight 8
visualViewport 8
localStream 8
parent 8
performance 7
AudioContext 7
locationbar 7
customElements 7
screenX 7
showSaveFilePicker 7
requestFileSystem 7
btoa 7
scrollBy 7
XMLHttpRequest 6
close 6
wrappedJSObject 6
history 6
requestIdleCallback 6
scrollY 6
screenY 6
showDirectoryPicker 6
localAudio 6
outerWidth 6
scroll 6
scrollByPages 6
mozRequestAnimationFrame 5
sessionId 5
scrollX 5
fence 5
afterprint_event 5
beforeprint_event 5
onerror 5
menubar 5
personalbar 5
scrollbars 5
statusbar 5
toolbar 5
print 5
document 4
fetch 4
hasRun 4
name 4
cancelIdleCallback 4
hashchange_event 4
popstate_event 4
onunhandledrejection 4
png 4
atob 4
remoteAudio 4
Promise 3
id 3
foo 3
Object 3
releaseEvents 3
external 3
event 3
moveTo 3
resolveLocalFileSystemURL 3
beforeunload_event 3
gamepadconnected_event 3
gamepaddisconnected_event 3
languagechange_event 3
message_event 3
messageerror_event 3
offline_event 3
online_event 3
pagehide_event 3
pageshow_event 3
rejectionhandled_event 3
storage_event 3
unhandledrejection_event 3
unload_event 3
PaymentRequest 3
caststatus 3
setImmediate 3
credentialless 3
focus 3
getDefaultComputedStyle 3
length 3
scrollByLines 3
start 3
webkitRequestAnimationFrame 2
msRequestAnimationFrame 2
webkitAudioContext 2
prop1 2
mozCancelAnimationFrame 2
setTimeout 2
webkitIndexedDB 2
sidebar 2
fullScreen 2
captureEvents 2
mozPaintCount 2
deviceorientation_event 2
devicemotion_event 2
moveBy 2
origin 2
clipboardData 2
InputEvent 2
EyeDropper 2
webkitRequestFileSystem 2
directoryEntry 2
onpagehide 2
PublicKeyCredential 2
getDevicePixelSize 2
peerStream 2
blur 2
frameElement 2
ongamepadconnected 2
ongamepaddisconnected 2
mozInnerScreenX 2
mozInnerScreenY 2
closed 2
onpopstate 2
onresize 2
scrollMaxX 2
scrollMaxY 2
stop 2
execScript 2
productionMode 2
main 1
structuredClone 1
oRequestAnimationFrame 1
ActiveXObject 1
NodeFilter 1
notify 1
messenger 1
Event 1
mozIndexedDB 1
routeEvent 1
mozAnimationStartTime 1
directories 1
login 1
onunload 1
ondeviceproximity 1
onuserproximity 1
ondevicelight 1
VTTCue 1
TextTrackCue 1
serviceWorker 1
webkitResolveLocalFileSystemURL 1
onsecuritypolicyviolation 1
FileSystemDirectoryEntry 1
DirectoryEntry 1
FileSystemEntry 1
Entry 1
webkitDirectoryEntry 1
HTMLDocument 1
IDBTransaction 1
webkitIDBTransaction 1
online 1
offline 1
AmbientLightSensor 1
FencedFrameConfig 1
SpeechRecognition 1
webkitSpeechRecognition 1
SpeechGrammarList 1
webkitSpeechGrammarList 1
SpeechRecognitionEvent 1
webkitSpeechRecognitionEvent 1
Worker 1
peer 1
RTCRtpSender 1
onafterprint 1
onappinstalled 1
back 1
onbeforeprint 1
caches 1
crossOriginIsolated 1
DeviceOrientationEvent 1
find 1
forward 1
onhashchange 1
onlanguagechange 1
onmessage 1
onmessageerror 1
navigation 1
onoffline 1
ononline 1
onorientationchange 1
originAgentCluster 1
scheduler 1
pageXOffset 1
pageYOffset 1
clearImmediate 1
showModalDialog 1
sizeToContent 1
status 1
onstorage 1
onvrdisplayactivate 1
onvrdisplayconnect 1
onvrdisplaydeactivate 1
onvrdisplaydisconnect 1
onvrdisplaypresentchange 1
global 1
dump 1
MSStream 1
variable 1
noFunc 1
BigInt 1
Date 1
Math 1
b 1
ga 1
isSecureContext 1
svgDocument 1

Script to collect them:

import FS from "node:fs/promises";

async function *listdir(dir) {
  const files = await FS.readdir(dir, { withFileTypes: true });
  for (const file of files) {
    if (file.isDirectory()) {
      yield *listdir(`${dir}/${file.name}`);
    } else {
      yield `${dir}/${file.name}`;
    }
  }
}

const nameToFiles = {};

for await (const file of listdir("files/en-us")) {
  if (!file.endsWith(".md")) {
    continue;
  }
  const content = await FS.readFile(file, "utf8");
  const windowMatches = content.match(/(?<=window[ \n]*\.)\w+/g);
  if (windowMatches) {
    for (const match of windowMatches) {
      if (!nameToFiles[match]) {
        nameToFiles[match] = [];
      }
      nameToFiles[match].push(file);
    }
  }
}

const namesAndFiles = Object.entries(nameToFiles).map(([name, files]) => [name, files.length]).sort((a, b) => b[1] - a[1]);

for (const [name, files] of namesAndFiles) {
  console.log(name, files);
}

[hamishwillee]

Not an easy question. I fit into the beginner category here - for example I find self.requestAnimationFrame() more readable than requestAnimationFrame(). The reason for this is that if you don't know the function is on window or the global scope of the browser, then it could be defined in the local scope - ditto for localStorage. How is a beginner supposed to know that this is the window-defined variable or is perhaps on the worker global scope?

That's why I'd prefer self. prefix for methods that work in any context and window. prefix for window methods that work only in window, and so on.
But I'm inconsistent on console because I think of it as a global object available everywhere, and self.console does look weird.
self.AudioContext looks even more weird.

Upshot, if we feel that we have to be consistent here (and I am not sure we do), then I think your proposal makes sense.

@wbamberg Would be good to have your opinion on this.