Please include the "Why" in your styleguide

[gionkunz]

Hi there

As your styleguide is getting popular I just wanted to express some concerns I have with it. I'm generally for styleguides, however, I believe that things are always depending on a context and if you're classifying something as bad / good you should always include a "why" and reason about your decision. There is nothing more frustrating than seeing developers which were trained to accept a fact that something is good or bad but they don't know the reasoning behind. Things can change from one day to the other and they will have no background to re-validate their decisions.

From an educational standpoint but also for future maintenance of your styleguide (as things are changing and you need to adopt) I strongly recommend you to include short reasoning in your examples why something is considered good or bad at that given time and context. One example would be in your type coercion entries. Why is it bad to use the unary + operator to convert a string to a number? In some context this makes absolute sense (both float and int can be converted, hex and exponent strings can be converted) and also it's faster than parseInt / parseFloat. If you include the "why" in your comments you can clarify your assumptions and the context.

There are also plenty of recommendations that are based on pure preference. Although, I prefer single quote over double quote string notation, and I have my personal functional explanation why I prefer them, there is no general explanation why they should be preferred. This is simply personal preference with some vague functional reasoning. I can imagine a lot of young developers following your styleguide will think that there is something wrong with double quotes and they will probably think JSON is ridiculously flawed and the jQuery source code (they prefer double quotes) is a pile of crap... I'd really also put a reasoning behind it and also explain that it's not necessarily a bad thing, whats really bad is not being consistent.

Thanks and I hope you agree to my motivation.

Cheers
Gion

[hshoff]

Hi @gionkunz thanks for checking out the guide!

We agree and we tried to add whys in the places it made sense. You can see the community opens up issues about "why" often: is:issue is:closed why and we try to address them as they come in.

We'll have more explanations in our upcoming ES6 style guide: #247

Some style rules are simply a stylistic preference. Often one style isn't better than another, you and your team just need to make a choice. The important part is consistency.

See Why does JavaScript need a style guide? #102 for
more on the importance of consistency.

🍻

[GochoMugo]

🆙 priority 🆙

[hshoff]

Hi @GochoMugo, to help us prioritize, which rules specifically could benefit from more explanation?

[GochoMugo]

In all instances where you compare different methods, one being bad and the other good.

For example,

// bad
var name = "Bob Parr";

// good
var name = 'Bob Parr';

// bad
var fullName = "Bob " + this.lastName;

// good
var fullName = 'Bob ' + this.lastName;

[ycdesu]

In the react style guide, it mentions "Always use double quotes (") for JSX attributes, but single quotes for all other JavaScript.". I wonder know why don't you apply double quotes for all javascript file. Isn't it more consistent? Thanks.

[goatslacker]

Because holding down the shift key every time you want a string kinda stinks. Your carpal tunnel will thank you for using single quotes.

Why double quotes in JSX? They only apply to JSX, and it's because HTML uses double quotes.

It's consistent in that JS = single quotes. JSX = double quotes.

[ycdesu]

ok, really thanks :)

[ondrejhanslik]

There are also some rules which are obviously only a matter of opinion (e.g. indendation tabs vs spaces). It would be nice to mark those, too.

[gaearon]

Why double quotes in JSX? They only apply to JSX, and it's because HTML uses double quotes.

I don't understand this argument, to be honest.
JSX is closer to JS than HTML.

In fact I always liked using single quotes in JSX precisely to highlight this isn't HTML.

[goatslacker]

Files that contain JSX aren't .js files, they're .jsx files. I believe this is mostly about aesthetics (similar to the semicolons vs no semicolons debate) and I'm not strongly in favor or opposed to anything.

I do believe the JSX is closer to HTML than JS though unless TC39 agrees to add it in as part of the language.

cc @ljharb

[ljharb]

(clearly all imo)

It's invalid JS syntax and almost valid HTML syntax - what its semantic purpose is closer to is irrelevant.

Similarly, nothing that's not spec-compliant JS should be in a .js file. JSX isn't spec-compliant JS, as such, it's not JS - it's a magical fairy language that happens to be very similar to JS :-)

Obviously you're free to use single or double quotes as you like - this styleguide has its recommendations, please fork it and alter them to meet your needs!

[nkbt]

The reason I agree on doublequotes, that things like emmet and webstorm automatically use them for jsx, which they treat more like html/xml (with some minor differences). So coding becomes just little more efficient, since we never need to type them.

But yeah, stylistic choice.

[gaearon]

Sorry for bikeshedding and taking your time. This is my last message in this thread, as you are the gatekeepers, and I trust you to make the decision.

what its semantic purpose is closer to is irrelevant.

This is where I have to respectfully disagree with you. I thought the purpose of Airbnb styleguide is to clarify the semantic purpose of the code wherever possible. In fact that's the nice thing about all the “Why?”s there: most rules actually help you write a less surprising code.

I do believe the JSX is closer to HTML than JS
It's invalid JS syntax and almost valid HTML syntax

If you look at React issues, you'll find people burnt by this far too often already:

facebook/react#4653
facebook/react#4433
facebook/react#2782
facebook/react#2781
facebook/react#1177

JSX is different from HTML (templates) in many fundamental ways: it doesn't support entities, doesn't use strings and interpolation, it doesn't have self-closing tags, it has attributes matching DOM property names rather than HTML attribute names (although not always, either!).

This is why I see preferring a semblance with HTML that soothes (and later confuses) beginner JSX users instead of highlighting the distinction as a backwards choice, inconsistent with the (practical) rest of the guide.

When we were transitioning a Backbone codebase to React, I used to catch parts of lazily copy-pasted HTML by the fact that it used double quotes. It can be a nice sanity check opportunity. It's useful to catch lazy copy-paste during reviews because people (including myself) would often forget to replace class with className, for example. This is not my “ultimate argument” (yes there are tools to convert HTML to JSX), but my point is that I found this visual distinction helpful when I was doing a lot of work both in HTML and JSX.

Thank you for reading through this.
I'm happy with whatever you choose, and I hope my perspective can be of help. Cheers!