Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

7
  • Thank you for the detailed answer. I had previously written a comment (since deleted) explaining that I was unable to format code blocks typographically in the current documentation (literally just a forum), but I have since discovered the option to switch to source code view in the editor. Commented Nov 7, 2023 at 12:56
  • Of the three options, I think the first one (using typography) is the way forward, as (to me) it appears clear and explains what should be replaced at the site it should be replaced. The HTML var element is new to me, so thanks for that! That will improve the content semantically and makes it easy to target the correct content in styles. Styling to show a literal gap is a nice idea, but this requires a comment after the line, which isn't so nice, to me. The last option is good too, but I can imagine that intentionally invalid code in the documentation may cause more harm than good. Commented Nov 7, 2023 at 12:59
  • 8
    For code examples, refactoring so that the input variables are explicitly defined is actually a far better approach to the code in general. Commented Nov 8, 2023 at 4:40
  • The variable option was what I was thinking, but the problem in javascript is that it's not clear from the variable declaration that the expected type is string. Maybe the comment could mention it. Commented Nov 8, 2023 at 21:24
  • 1
    I think one thing I like about the first option is that it uses regular sentence formatting (i.e. a prompt with spaces between each word). The OP doesn't have spaces and the brackets make it look like the expected value is code. I have worked on applications where an argument is a string type which can be code which is dynamically reinterpreted. So I might have thought that [CustomerReference] is automagically updated with my reference number. Commented Nov 9, 2023 at 15:10