A JavaScript Quality Guide | Hacker News Reader

A JavaScript Quality Guide

github.com

86 pointsbevacqua68 comments

If you're going to have your team agree on any style rules at all, then automated style checking is the only way to go.

Let the computer yell at people so you don't have to.

Nobody wants to be the pedantic jerk who has to leave comments on a PR about whitespace or single vs double quotes.

When you use an automated style checker, you presumably catch those errors before a PR gets submitted and nobody ever has to be the bad guy/girl.

> automated style checking is the only way to go

Absolutely. We've found automated style checking also improves quality and efficiency. Even the "pedantic jerk" can miss small style issues that are easily caught by tooling.

For anyone wondering what tools. The most common for JS are JSHint and JSCS. Then use Grunt or Gulp combined with a watch to check a file each time a change is saved. Lastly, use a precommit hook (or similar) to check again before code is committed into the repo.

I learned something: I didn't know that the difference between:

    function foo() {
    }

and

    var foo = function() {
    };

Was that with the first form foo() will always be declared and available for use inside a scope, while the second form depends at which point it is declared.

But I had read somewhere (can't remember where... jshint?) a long while ago that using the latter form inside scopes was better, so I've adopted that.

I don't think I will go with the guide for this one, since not having the function defined automatically is often useful, to avoid overhead of instantiating the function for when it's not going to be used due to code flow.

That's negligible, the code is going to get compiled in C++ anyways, and the overhead is minimal

I don't understand why you bring up C++.

With overhead, the approach I try to stick to is unless the code become more difficult to grasp, avoid overheads, however small they may be, whenever they can be avoided. Everything adds up in the end.

A lot of people prefer the latter form inside scope, because it disambiguates the ambiguity that hoisting introduces: define your function at the bottom of the scope, and it'll still be available at the top. By assigning it to var, you delineate "this function can be called by any line in this scope after this one, but not by any line before it." You also remove a named reference to it from the stack trace.

I much prefer dealing with the "weird" "confusion" hoisting behavior than with not having a named function in my stack trace.

Fortunately they're not mutually exclusive, which is why the one true way (tm) is:

    var foo = function foo() {
    };

EDIT: The reason it's better to avoid hoisting is because global variables are almost always wrong.

Pretty sure hoisting is totally unrelated to global variables. If a function is defined in a scope, it'll only be hoisted to the top of the scope.

Ah, right. Should have left the original comment alone.

Here's why you shouldn't rely on function hoisting: it gets weird. Weird enough that MDN has a section on it's "oddities" [0]. And since it doesn't add any expressive power, there's no compelling reason not to just treat all your code as data.

[0]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

That sounds like an argument for learning how hoisting works, not just avoiding it because it's "weird".

Or limiting when/where you define named functions it's pretty damn silly to declare a named function within an if block within a function call, especially if it has the same name as a function you've defined outside of it.

I tend to limit them to "private" module functions. e.g.,

  "use strict";
  /*global module:true*/

  function add(a, b) {
    return a+b;
  }

  module.exports = {
    sum : function(list) {
      return list.reduce(add, 0);
    }
  };

I don't declare named functions in a scope smaller than the module itself, so I don't really run into the 'weirdness' of hoisting.

Then again, I've moved to commonjs style modules for everything - server side with node, client side with browserify (webpack does weird things with require()).

I'd be in complete agreement if it offered any substantive benefits; however, I've yet to see an example of function-hoisting that can do something regular var-hoisting can't.

It lets you put your functions where you want, for readability, but still be able to use them where they need to be used.

So does regular var-hoisting, which every JS developer already needs to know.

That doesn't avoid hoisting though ;)

Yes, actually it does. A named function expression and a function declaration are distinct concepts. The latter is function-hoisted (the whole body goes to the top), whereas the former is only var-hoisted (the body remains in place).

What browser are you using? As far as I can tell, all modern browsers know how to get the name of a function defined like `var foo = function(){}` for stack traces.

This is referred to as "hoisting". As an aside, technically the latter's `var` declaration also gets destructured and hoisted as such...

  var foo;
  ...
  foo = function() {

  }

Also another difference in the latter is that its an anonymous function, which is commonly seen in assignment expressions — but you could also name it for more informative logging.

  var foo = function realName(){};

> more informative logging.

> var foo = function realName(){};

Nice trick, thanks! The "anonymous" function is especially annoying when profiling code, so that should address that annoyance. I often struggle with picking names, but another post here shows that "foo" can just be reused as the function name.

> I often struggle with picking names, but another post here shows that "foo" can just be reused as the function name.

I'd be very careful about giving them the same name if you're working with IE at all. IE8 and below's JScript does some really strange stuff with function expressions, leaking and hoisting them all over the place. [1]

Instead, I'd just append a character or something to differentiate the two. I've been using the format advocated for in Javascript Patterns[2][3]:

    var foo = function fooF(){};

[1] http://kangax.github.io/nfe/#jscript-bugs

[2] http://shichuan.github.io/javascript-patterns/

[3] https://github.com/shichuan/javascript-patterns/blob/master/...

Thanks for the tip, adopted. The kind of tip that might have saved me a lot of time in the future.

Naming the anonymous functions, is actually suggested as good practice somewhere in the Angular.js docs. I came across that a couple of weeks ago.

Naming anonymous functions (and anonymous function expressions) provides useful context while tracing error stacks

This was exactly the reason it was suggested in the Angular.js docs.

One gotcha about naming otherwise anonymous functions is that the function name is often removed during minification.

So, if you have code or logging that assumes all functions have names, then the code may break or degrade when built and deployed in production.

I was under the assumption that we'd pretty much settled on the second syntax.

I've prefer the latter as it better illustrates the way JavaScript actually works, with all methods being lambdas. The prior is just too magic.

The first chapter of JavaScript Allongé explains this really really well https://leanpub.com/javascript-allonge/read

> Always put 'use strict'; at the top of your modules.

'use strict'; should be in the top of the scope you control. A global 'use strict'; would place the global scope into strict mode, so all your imported modules would be under strict mode too, and then third party code would break and you don't know why. IIRC jshint will pick this up.

To be honest, the whole guide seems like a shorter, less comprehensive version of the JS community's own Idiomatic JS https://github.com/rwaldron/idiomatic.js/

That's what that means. In CommonJS the top of the module is the topmost scope, in systems like RequireJS its the first thing in your closures

I'm not convinced that this guide is very good. On many of the issues the actual decision is punted in favor of "just make sure it's consistent". Well obviously, that's why there's a guide. The purpose is to lay down the law so everyone knows HOW to be consistent.

Moreover, a few of the suggestions introduce serious performance issues, notably around iteration and the treatment of the `arguments` object. If you haven't yet, please do check out Petka Antonov's Optimization Killers [0].

[0]: https://github.com/petkaantonov/bluebird/wiki/Optimization-k...

It really depends on whether performance is an issue, and the cost of the optimisation.

A common example: lodash searches function toString() with regexps as an optimisation technique, underscore doesn't. Both are correct, maintaining lodash requires knowledge of how and why the hack works, but OTOH lodash is faster. Maintaining underscore is cognitively simpler but the resulting code is slower.

I'm all about making sure that code is optimized for humans first and computers second.

Here is the specific remark I was referring to: Or even better, just use .forEach which doesn't have the same caveats as declaring functions in for loops.

Blindly applying forEach is simply not the right answer here.

I'd suggest the opposite: forEach() is smaller that iterating over indexes and creates a scope by default which (although having overhead) will prevent a lot of common last-case-wins scenarios that frequently trap both new and experienced developers.

Should we use a .forEach() for a 1 million item array? No. Performance would be a problem. For the typical use case of items like the demo [1, 2, 3]? Yes, this would be be simpler.

The best quality/style guide I've ever been given was: "our code will be read many more times than it was written, don't do stupid shit". Having worked in that team for a while I really can't see any use for this kind of granular detail, other than if you goal really is over-zealous control.

Not really sure we need another one of these: Idiomatic.JS[1] is far more complete, and if you want an opinion, just seek the style of Google[2].

[1] = https://github.com/rwaldron/idiomatic.js/

[2] = https://google-styleguide.googlecode.com/svn/trunk/javascrip...

> Keep regular expressions in variables, don't use them inline. This will vastly improve readability.

Although it might introduce inadvertent bugs. I prefer not to follow that advice to avoid running into the 'lastIndex' problem described here [1]. There are other ways to avoid it like not using the 'g' flag or resetting lastIndex. However not storing regex in a variable is also useful to avoid that headache. You might argue about performance but for a good majority of the cases, it doesn't matter practically.

[1] http://stackoverflow.com/questions/1520800/why-regexp-with-g...

[2] http://stackoverflow.com/questions/13500519/difference-betwe...

  Semicolons ;

It seems to be fashionable recently to omit semicolons from Javascript. For example GitHub (internal) and zepto.js have jumped on the no-semicolon bandwagon, requiring their omission in any code.

http://programmers.stackexchange.com/questions/142086/why-th...

OP's guide mentions "Avoid headaches, avoid ASI. Always add semicolons where needed", that's a good advice IMHO.

Edit: I would add: http://programmers.stackexchange.com/a/142114

> Always add semicolons where needed

Perhaps overly pedantic, but this seems a little...vague.

That's why I don't like guides that suggest people to mindlessly add semicolons everywhere. If you don't really know how ASI works you are always living in the fear of missing a semicolon somewhere. Actually learning how ASI works liberates you from that fear and you can still opt to use or not use semicolons.

I think I'm actually in total disagreement with this. I think using semicolons as statement terminators is quite easy and doesn't require any knowledge of the ASI in terms of _adding_ semicolons. The one (potential) issue with not being aware of the ASI when using semicolons as statement terminators is for something like:

  return
    {
      a: 0
    };

since you can't disable ASI. Even in the above case, however, "standard" JS style would prevent the issue.

Relying on "standard JS style" is as reliable as relying on ASI without knowing how it works.

If what you are saying is with "standard JS style" you will never add a newline after return, then I can also assume with "standard JS style" you will not:

- start a line with ++ or --

- start a line with a regex literal

- split a for statement into separate lines

So, the only issue you need to be aware of when writing semicolon-less javascript is when you start a new line with ( or [. Easy enough to remember, no?

I've personally been writing semicolon-less JS for almost two years now, and this one simple rule has been more than enough.

http://inimino.org/~inimino/blog/javascript_semicolons

Don't confuse quality with style. If you want provide a quality guide, include only rules that actually improve the quality of the code, don't include style preferences. Style is subjective by nature, but quality not so much. Some rules being enforced in this guide are heavily opinionated and yet have no direct correlation with code quality. What does the indentation being 2 spaces or 4 spaces or tabs have to do with code quality? And a semicolon-less codebase can be as clean, readable and performant as one with semicolons, your arguments against ASI is simply FUD. As many have pointed out, for these stylistic disagreements the only rule should be "just be consistent".

I'm confused by what "Style checking" (https://github.com/bevacqua/js/#style-checking) means.

Aren't many of the other suggestions precisely "style checking" concerns? Semicolons, spacing, string quotes, conditional brackets, etc. ?

Not to say that there isn't a difference -- just that I don't see what it is.

Automated style checkers such as jscs

[1]: https://www.npmjs.org/package/jscs

That doesn't answer my question as far as I can tell, unless you're saying that:

      "Style checking" means "Automated style checkers such as jscs"

what's the difference between a style checker like jscs and a linter like jshint/jslint?

They are similar and have some overlap. However, the overlap is not 100%, so it's good practice to use both jshint and jscs together.

jshint is a static code analysis tool to identify and flag errors/potential errors in JS code. jscs is purely a style checker.

I've been using JSLint with default options for years now. It's blissful not having to think about this stuff anymore.

Is this similar to https://github.com/airbnb/javascript ?

Don't sweat the small stuff.

Really how you place your {} will never make or break your project. Focus on what really matters.

Glad you got that. Some people are adamant of letting go of their obnoxious style checkers that do nothing but waste everyone's time

https://github.com/bevacqua/js/issues/2

See http://programmers.stackexchange.com/a/142114

Does this do something more than jshint?

there is no code it's just an markdown text file.

     var message = util.format('oh hai %s!', name);

I thought it was a javascript quality guide ? there is no util.format in ES5 spec.

It's a Node.js example

"Usually you'll be a happier JavaScript developer if you hack together a parameter-replacing method like util.format in Node." + "You could implement something similar using the piece of code below."

I don't think you can ask more than this, everything is clearly laid out...

You lost me at 2 spaces

Stopped reading after 2 spaces. 4 spaces is the law!

I think you'll find that most frontend developers despise 4 spaces...at least that I've come upon anyhow. I only ever met one developer that liked 4, and that person is a tab guy to boot.

I'm a front-end guy and I love my 4 spaces. Helps a lot with complicated HTML to have the extra spaces to easily see what is what. It's also very useful in SASS and Less, where you have nesting.

"I'll think you find that most..." is the start of no compelling argument ever 0o

Oh oh lets fight ;-) 2 Spaces, 4 Spaces, 1 Tab (view as 2 Spaces or 4 Spaces).

Important is to configure once your favorite Editor and use it consequent.

As someone who prefers tabs, but doesn't care enough so will happily use spaces, I've never understood the hatred around tabs.

Not only does it remove the 2 vs 4 spaces debate (just set your browser preferences to display it as whatever!), it's more 'semantically correct' - it's literally saying "one level of indentation please".

Anyway, not that I particularly care - I just always found it amusing that this is where developers have chosen against things being semantically correct and user-configurable.

I used to prefer tabs (for the exact reason, tabs indicate an indent, spaces indicate a space) except for one edge case that has me using spaces now. If you're anal about making sure chained method calls line up on their own lines, spaces guarantee that across the board, but tabs would mess up the indent.

  var foo = SomeTerriblyLongHorrificClass->withUnreasonablyLargeChildren()
                                         ->dueToTheOddNumberOfCharachters()
                                         ->sometimesItsNiceToUseSpaces()
                                         ->here()

If you were really committed, you would have renamed your names to force them to line up with tabs :)

i like this guy

Reply on news.ycombinator.com