The correct JavaScript syntax box for callbacks

MDN
#1

I’ve saw two styles while reading built-in objects for JavaScript.

// Let's assume that all callback parameters are explained at h3.Parameters, regardless of its style.
someFunction(callback[, optionalArg]); // first style, callback params are not written here.
someFunction(callback(cbArg[, cbOptionalArg])[, optionalArg]) // second style, callback params are explicitly written here.

For the first example see Array.prototype.find().
For the second, see Array.prototype.findIndex().

Please note that find() was changed from the first to the second and reverted, which made me curious.

ECMA-262 6th edition uses the first style (Array.prototype.map( callbackfn [ , thisArg ] )) so is it safe to think that I should prefer callbacks without parameters?

#2

This is not something I’ve thought about, but it is a good idea for us to do this consistently. Thanks for bringing it up.

In the WebAPI documentation, I tend to always write it without including the cb params, as it is less confusing. The cb params can then be explained somewhere below.

I think @fscholz also stuck to this style in the JS built-ins docs, but confirming this would be good.

Once this is confirmed, I can also add a note about this to the MDN code style guidelines.

1 Like
#3

Yeah, I think without the cb params is fine.

Also, a bit more than two years ago, I was suggesting to not have the square brackets anymore: https://groups.google.com/d/msg/mozilla.dev.mdc/eS12O5mAI-A/J1Qd-HajBgAJ

Instead, I was proposing to list multiple (or all) variations of how you could use a method in separate lines.

Anyway, it would be good to agree on something and to have consistency.

1 Like
#4

As a documentation, I prefer bracket syntax over multiline for its single line cleanliness. But I admit, I found it quite hard to grasp at the beginning.

Listing variations has its place too. For me, a good example of combining brackets + variations was Date constructor.

Maybe add a help button inside syntax boxes, which appears when hovered and links to some page, that describes syntax-box-syntax? I couldn’t find such page (yet), reading this Wikipedia is too much, and it would help to reduce questions such as this.

For the main topic:
I’ll prefer parameterless callbacks. Thanks! Syntax sections page needs updates too. It could be used as a help page.

1 Like
#5

It is funny how many times these kinds of discussions keep occuring. Now that @fscholz included the link to the previous discussion, I remember it :wink:

It also makes me sad, as since he updated the slice() page with the easier syntax, it got reverted again to the formal syntax.

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice$compare?locale=en-US&to=1352049&from=1135439

I’d love to spearhead an effort to change all of these, but I worry that we won’t find the time. Perhaps we could do this as part of the page maintenance plan we are proposing to put into action this year: https://docs.google.com/document/d/1_ryTfwcvLOr1b75ekVh590BaJfz_rUo-E_f-jTbSbUU/edit#

When we do maintenance on the JS pages?

In the meantime, for the code style guidelines I completely forgot I’d written that Syntax sections doc :wink: I can just update that and link to it instead — see here https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Writing_syntax_sections_on_reference_pages

I also updated the Syntax sections doc with some more information about formal syntax and why we prefer not to use it, alternatives, etc. https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Syntax_sections#Constructors_and_methods

1 Like
#6

Though I personally prefer traditional bracketed syntax for optionals, I conceded last year that expecting newcomers to know that syntax wasn’t logical, and so I’ve started using multiple lines of syntax forms to describe different sets of parameters to a function, and any optional parameters are just noted as optional using {{optional_inline}} on the <dt> line indicating the parameter name in the <dl> below. I can live with that. :slight_smile:

1 Like
#7

Another option might be to use question marks ? instead of brackets, which is also what TypeScript uses for optional parameters in its extended syntax.

1 Like