I'm looking at majority of examples and everyone tends to use var keyword instead of using let and const. Stack Overflow's documentation is very young right now and shouldn't we use modern approaches to make it more up to date?
-
3Difficult. I would say "too soon", var at this point in time is still far more portable.– GimbyCommented Jul 22, 2016 at 12:21
-
1If the example is marked for versions 6 and above, sure.– Heretic MonkeyCommented Jul 22, 2016 at 14:29
-
3Only if the example is ES6 specific.– CerbrusCommented Jul 26, 2016 at 8:49
4 Answers
If the example is for an ES6+ feature, like arrow functions, it should be recommended to default to const
, and then to let
if a variable will change.
If the example/feature is ES5-, then you should use var
.
Not using const
/let
because a browser does not support it yet would not properly reflect the specification/feature that you're documenting.
If you must, prefix your documentation with the fact that you will need to use var
for legacy browsers, or for browsers that have not yet implemented the specification.
Do not sacrifice good/accurate content for browsers that lag behind.
-
This. ES6 support is high enough that documentation should now promote the bleeding edge scope, regardless of browsers too slow to keep up. Commented Aug 1, 2016 at 15:17
The current version of Safari (9.1) does not support let
or const
so I would recommend not using it in documentation for now. Unless their is a specific reason for using those, I think it could be confusing for new programmers.
-
3One browser with minimal use (<2%) doesn't support it for the next few months. That's not a reason to avoid a best-practice in answers, especially not when the legacy alternative is typically a search-and-replace.– ssubeCommented Aug 1, 2016 at 14:47
-
2@ssube 2% sounds small. 2% of 3 billion, though... 60 million people is a pretty significant number! Commented Aug 1, 2016 at 14:55
-
2@JonStory that's why you provide a fallback. We're not writing examples for those 60 million people directly, we're writing examples for the developers. To make the examples as clear as possible, using best practices should always be encouraged. To make the examples relevant, including a fallback for older browsers is a great idea.– ssubeCommented Aug 1, 2016 at 15:17
-
2@ssube: That means a massive portion of the JS documentation would have to link to / describe the
var
fallback. I'd rather go for ndugger's option: If you're documenting ES6+ features, use the new declaration types. If you're documenting older features, just usevar
.– CerbrusCommented Aug 1, 2016 at 15:19 -
3It should be noted that the beta SF10 has 100% ES6 support. Don't let SF9's ~50% sway a critical documentation curve when it will soon be legacy. All major browsers once SF10 is released non-beta will be 95%+ support. That's enough to denote ES6 documentation in my books. Commented Aug 1, 2016 at 15:21
Yes, but provide a fallback.
const
and let
are the current best-practice, which is absolutely something we want to promote. On top of that, block scoping can clean up your examples here and there.
Unfortunately, they aren't supported in every runtime, so we need to provide some alternative. The equivalent with var
is pretty similar, so copying your example and adding a second one without const
/let
will make your answer useful to everybody.
-
1Are you suggesting providing two nearly identical examples per example? that seems bad..– Kevin BCommented Aug 1, 2016 at 15:19
-
@KevinB when the question needs ES3/5, then yes. It is bad, but sometimes we have to support old browsers. If the question is already ES6 (OP started with it) or there are no real differences, then a simple note to ctrl-r is plenty.– ssubeCommented Aug 1, 2016 at 15:20
I think the best way would be to use the version syntax to denote examples and use the best practises of each version.
Sadly, if you only want to introduce const
at the moment this means to duplicate the example into a separate version block. That sure is a maintainability nightmare. There should be a more sophisticated version system that allows such small variations without duplicating the whole code.