website-v2 icon indicating copy to clipboard operation
website-v2 copied to clipboard

Use msg more in documentation code snippets

Open mybearworld opened this issue 2 years ago • 3 comments

For example, https://scratchaddons.com/docs/develop/userscripts/best-practices/ has the following code snippet:

// Do this instead:
document.querySelector(".remix-button").addEventListener("click", () => {
  prompt("Are you sure you want to remix?");
});

Which probably should be something like:

// Do this instead:
document.querySelector(".remix-button").addEventListener("click", () => {
  prompt(msg("remix-confirm"));
});

mybearworld avatar Apr 30 '23 09:04 mybearworld

That specific example is about XSS, so using msg() there can make it confusing. It becomes more complicated to explain because safeMsg would also be worth mentioning. Also, the reader might incorrectly interpret that msg() avoids XSS, instead of el.textContent.

I guess we could add a code comment such as: // Note: real userscript code should use msg() here

WorldLanguages avatar Apr 30 '23 16:04 WorldLanguages

That specific example is about XSS, so using msg() there can make it confusing. It becomes more complicated to explain because safeMsg would also be worth mentioning. Also, the reader might incorrectly interpret that msg() avoids XSS, instead of el.textContent.

I guess we could add a code comment such as: // Note: real userscript code should use msg() here

True, that specific example was poorly chosen, I'll replace it with another one.

mybearworld avatar Apr 30 '23 16:04 mybearworld

I believe we should keep the current examples, but we could add a comment such as // Note: real userscript code should use msg() here next to the lines that use hardcoded strings.

WorldLanguages avatar Apr 30 '23 19:04 WorldLanguages