Newspaper metaphor support

The newspaper metaphor (introduced by Robert C. Martin in his book Clean Code) is a useful concept that puts the highest-level code to the top, so it’s easy to figure out the high-level goals of a module or class. Because you start reading at the top, which is what we usually do anyway. But if it starts with the implementation details, it’s much harder, and I usually ask myself: why is this function needed, where is it going to be used? It’s a constant struggle for me.

Your style guide never mentions the newspaper metaphor, which is somewhat incompatible with your view that “functions should not be used before they are defined”:

Functions

[7.1](https://github.com/airbnb/javascript#functions--declarations) Use named function expressions instead of function declarations. eslint: [func-style](https://eslint.org/docs/rules/func-style)

    Why? Function declarations are hoisted, which means that it’s easy - too easy - to reference the function before it is defined in the file. This harms readability and maintainability.

Even the ESLint rule description fails to talk about the newspaper metaphor:

https://eslint.org/docs/latest/rules/func-style

But, the biggest problem is not hoisting, IMO. It’s the use of var. When we only use const or let, the newspaper metaphor can be used most of the time:

const main = function() {
  lowerLevelFunc();
}

const lowerLevelFunc = function() {
}

// This would normally be the first line...
main();

Not perfect, sadly. The language limits us here. But that doesn’t mean we should introduce a style guide that makes the situation even worse.

(Off topic, but I pretty much agree with this comment: https://github.com/airbnb/javascript/issues/794#issuecomment-656928852 , i.e., not giving functions 2 names. If people can’t keep their browsers updated, then they will inherit the security vulnerabilities too.)

Also, I would consider the use of arrow functions almost everywhere (i.e. function expressions), for the reason that this cannot be overridden by callers, which reduces mental complexity or any defensive code to be written. But the world does not always agree:

https://davidwalsh.name/i-dont-hate-arrow-functions

(In short: a function that looks like a variable assignment is confusing and not easy to read.)

Then, is it really worth standardizing the way we declare functions? For callbacks, sure, I agree, but for higher scopes, the picture isn’t clear. It’s more like a language design problem for which a straightforward solution cannot be given currently.

[rkrisztian]

I think your guide is one of the best out there, seems very thoroughly thought out, even given explanations not just rules, so I do plan to follow, I just couldn’t get my head around this one problem. Thanks for the explanations you gave so far.

[ljharb]

The point of style guides is to enforce largely subjective rules in an opinionated fashion. If it were objective, no guide would be needed.