[ANN] Updated Javascript Best Practices document

[Matt Kruse]

http://www.javascripttoolbox.com/bestpractices/new.php

I've updated my Best Practices document to include more content and more
supporting arguments for the recommendations. Also, I've added #anchors to
each recommendation so linking to a specific recommendation is possible from
posts here, etc.

I would love to get feedback from the experienced developers here. If you
see any technical errors or have any suggestions, please let me know so I
can update the document before making it "live".

The TOC is as follows:

1. Always Use 'var'
2. Feature-Detect Rather Than Browser-Detect
3. Use Square Bracket Notation
4. Avoid 'eval'
5. Reference Forms and Form Elements Correctly
6. Avoid 'with' Statements
7. Use onclick In Anchors Instead Of javascript: Psuedo-Protocol
8. Use The Unary + Operator To Cast To Number
9. Avoid document.all
10. Don't Use HTML Comments In Script Blocks
11. Avoid Cluttering The Global Namespace
12. Avoid prototype.js
13. Avoid sync "Ajax" calls
14. Use JSON
15. Use Correct <script> Tags

 

[gg.20.keen4some]

I would love to get feedback from the experienced developers here.

I'm no javascript expert, but I do have lots of traditional software
dev experience, so take this comment for what it is worth.

Does javascript have any accepted variable naming conventions? If so,
that would be a good addtion to your document. At present, the first
example shows a global variable named 'i'. *You* know that is not a
good name for a global variable. *I* know that. Probably most of the
other readers of this group, know that. But a new programmer might not
know that!

As I say, FWIW.

TC (MVP MSAccess)
http://tc2.atspae.com

 

[TC]

I would love to get feedback from the experienced developers here.

I'm no javascript expert, but I do have lots of traditional software
dev experience, so take this comment for what it is worth.

Does javascript have any accepted variable naming conventions? If so,
that would be a good addtion to your document. At present, the first
example shows a global variable named 'i'. *You* know that is not a
good name for a global variable. *I* know that. Probably most of the
other readers of this group, know that. But a new programmer might not
know that!

As I say, FWIW.

TC (MVP MSAccess)
http://tc2.atspae.com

 

[TC]

Oops (URL error):

http://tc2.atspace.com

TC

 

[Randy Webb]

(e-mail address removed) said the following on 6/1/2006 1:53 PM:

I'm no javascript expert, but I do have lots of traditional software
dev experience, so take this comment for what it is worth.

Does javascript have any accepted variable naming conventions?

Only traditional. And the oft argued idea of using $varName that is
currently being argued. And you often see comments about "Dont use
VarName, use varName" as something somewhere in some pedantic place of a
useless/worthless ECMAScript document says something moronically
unrelated about it.

If so, that would be a good addtion to your document. At present, the
first example shows a global variable named 'i'. *You* know that is
not a good name for a global variable. *I* know that. Probably most of the
other readers of this group, know that. But a new programmer might not
know that!

Whether it is a good variable name or not depends on context.

for (var i=0;i<someNumber;i++){

Is a very well established convention.

Whereas:

var i = document.getElementById('someID').style.visibility;

is indeed a bad idea as that var should (but doesn't have to) give some
indication of what the var is for.

 

[Michael Winter]

(e-mail address removed) said the following on 6/1/2006 1:53 PM:
[snip]

Does javascript have any accepted variable naming conventions?

Only traditional. [...] And you often see comments about "Dont use
VarName, use varName"

That, too, is traditional and borrowed from other languages. I for one
am used to seeing an initial capital letter only with constructor
functions (class/type names in other languages).

as something somewhere in some pedantic place of a useless/worthless
ECMAScript document says something moronically unrelated about it.

It has nothing to do with the ECMAScript specification, and please don't
start writing things like that. Seriously, you'll come off like VK
ranting about how the W3C are out to get the Web. You don't want that,
do you?

[snip]

Mike

 

[TC]

Whether it is a good variable name or not depends on context.

I was commenting specifically on its use as a /global/ varable name. I
hope you'd agree that 'i' is not good as a global name!

As for temporary/local variables like loop indexes, I couldn't agree
more - the simpler the better. I can't stand ridiculous things like
below (whch aren't uncommon in Visual Basc for Applications code):

Dim tmpNumericIndex as integer, strTemporaryStringValue as string
for tmpNumericIndex = 1 to 10
strTemporaryStringValue = blah(tmpNumericIndex)
if strTemporaryStringValue = .. etc.

Geez! Save the trees, use 'n' and 's' already!

Cheers,
TC (MVP MSAccess)
http://tc2.atspace.com

 

[Michael Winter]

On 01/06/2006 17:14, Matt Kruse wrote:

[snip]

After a quick look...

2. Feature-Detect Rather Than Browser-Detect

I question the else branch in the example, just because it might seem
like telling the user arguably useless information is a good idea (this
is a 'best practice' document, after all).

3. Use Square Bracket Notation

You initially refer to 'object notation', then switch to dot notation.
Stick to the latter.

[snip]

7. Use onclick In Anchors Instead Of javascript: Psuedo-Protocol

You spelt 'pseudo' wrong in the title.

[snip]

Mike

 

[Matt Kruse]

I was commenting specifically on its use as a /global/ varable name. I
hope you'd agree that 'i' is not good as a global name!

I agree, i as a global variable name is bad. But it's just a simple example.
I later discourage global variables entirely, so I think it's fine

 

[Matt Kruse]

I question the else branch in the example, just because it might seem
like telling the user arguably useless information is a good idea
(this is a 'best practice' document, after all).

Hmmm, I was just trying to point out that the case needs to be handled where
the browser lacks the capability to perform a task. In some cases, it may
mean notifying the user. Probably not in most cases. Any suggestion for a
better example?

You initially refer to 'object notation', then switch to dot notation.
Stick to the latter.

Yup, typo, fixed it.

You spelt 'pseudo' wrong in the title.

Another typo, fixed it.

Thanks!

 

[Dr John Stockton]

JRS: In article <[email protected]>, dated Thu, 1 Jun 2006
11:14:37 remote, seen in Matt Kruse

The TOC is as follows:

1. Always Use 'var'

Can't do that (AFAIK) when one wants to write a function whose purpose
is to create and maybe initialise global variables.

4. Avoid 'eval'

4. Don't misuse 'eval'

8. Use The Unary + Operator To Cast To Number

The action referred to does not map very well onto the established use
of 'Cast' in other languages. Is there a better term?


101. Use whitespace for legibility
102. Put repeated code into a function
103. Put material used in multiple pages into an include file
104. Internationalise, don't multinationalise.

 

[Matt Kruse]

Can't do that (AFAIK) when one wants to write a function whose purpose
is to create and maybe initialise global variables.

In what case would you want to initialize global variables?
That seems to conflict with the recommendation below to avoid global
variables, also.

The action referred to does not map very well onto the established use
of 'Cast' in other languages. Is there a better term?

I wondered the same thing, if there was a better term. Maybe "Convert To
Number" instead?

 

[Randy Webb]

Michael Winter said the following on 6/1/2006 2:53 PM:

(e-mail address removed) said the following on 6/1/2006 1:53 PM:
[snip]

Does javascript have any accepted variable naming conventions?

Only traditional. [...] And you often see comments about "Dont use
VarName, use varName"

That, too, is traditional and borrowed from other languages. I for one
am used to seeing an initial capital letter only with constructor
functions (class/type names in other languages).

While that is true about other languages, it doesn't mean its a bad
practice in Javascript

And don't get me wrong, I don't name them with first letter uppercase. I
just don't see any harm in it and have never read anything definitive
that says it is harmful in JS.

 

[Michael Winter]

Michael Winter said the following on 6/1/2006 2:53 PM:

On 01/06/2006 19:30, Randy Webb wrote:

[snip]

[...] And you often see comments about "Dont use VarName, use
varName"

That, too, is traditional and borrowed from other languages. I for
one am used to seeing an initial capital letter only with
constructor functions (class/type names in other languages).

While that is true about other languages, it doesn't mean its a bad
practice in Javascript

I never said it was.

And don't get me wrong, I don't name them with first letter
uppercase. I just don't see any harm in it and have never read
anything definitive that says it is harmful in JS.

Harmful? Certainly not, though it might not be the expected convention.

Whatever convention is used, it should be well-documented, easy to
follow, and consistently applied. Of course, that's just common sense.

Mike

 

[Michael Winter]

Hmmm, I was just trying to point out that the case needs to be
handled where the browser lacks the capability to perform a task.

Sure, I know. I just think one should be a little careful with what goes
into a 'best practice' document. Allowing someone draw the wrong
conclusion is one thing, but doing so whilst letting them think it's the
best thing to do is another.

In some cases, it may mean notifying the user. Probably not in most
cases.

Agreed on the second point. "You can't use this Web page." What's the
user to do about that (other than go elsewhere)? The rule of thumb is
not expose the user to implementation or technical details (unless
they're actively looking for them, perhaps) as more often than not,
those details are entirely unhelpful.

Any suggestion for a better example?

Unfortunately, no. You know as well as I do that the correct solution
would vary based on the circumstances at hand. For example, if the
script performs augmentation of the document tree, it's often best to do
nothing and hand over to the server, letting it do the augmentation by
serving the document anew.

[snip]

Mike

 

[Michael Winter]

JRS: In article <[email protected]>, dated Thu, 1 Jun 2006
11:14:37 remote, seen in Matt Kruse
<[email protected]> posted :
[snip]

8. Use The Unary + Operator To Cast To Number

The action referred to does not map very well onto the established use
of 'Cast' in other languages. Is there a better term?

Type-convert or coerce?

[snip]

Mike

 

[Randy Webb]

Michael Winter said the following on 6/2/2006 10:51 AM:

JRS: In article <[email protected]>, dated Thu, 1 Jun 2006
11:14:37 remote, seen in Matt Kruse
<[email protected]> posted :
[snip]

8. Use The Unary + Operator To Cast To Number

The action referred to does not map very well onto the established use
of 'Cast' in other languages. Is there a better term?

Type-convert or coerce?

Type Convert

 

[VK]

I'm trying to write my page so that there is a div with a message like
this that is set to visible by default in the stylesheet, but hidden early
on in the app's initialisation process.

Uhm... Any particular reason to not use <noscript> instead?

 

[Matt Kruse]

Uhm... Any particular reason to not use <noscript> instead?

Just the obvious reason that noscript will run only if js is completely
disabled, not if certain features are not available in the js/dom
implementation.

If your code depends on document.getElementById and someone is using IE4.0
with js enabled, they wouldn't see noscript content, but they also wouldn't
be able to run your code.

 

[VK]

Just the obvious reason that noscript will run only if js is completely
disabled, not if certain features are not available in the js/dom
implementation.

Uhm... (second one already ;-) These are two completely different
situations here:

1) scripting is completely disabled/not supported, so no client-side
scripted page adjustment is possible. INHO this is what the poster was
talking about. <noscript> is an obvious solution specially made for
such situation.

2) scripting is allowed but no guarantees what this of that feature is
supported. Here it's the question of feature detection and graceful
degradation so many times mentioned in this group. This process doesn't
involve any alerts or red-framed div's of like "Your browser doesn't
support document.getElementById". It is up to the internal script job
to handle the troubles. Regular visitor is not interested in the list
of missing features, however nicely styled it (the list) would be.

2-a) script is needed to run once on load for a particular browser to
make it able to handle some content. A "particular browser" is for
example IE, where you have to add extra namespaces to handle say VML or
MathML. This is handled by using specific content type for your script:

<script type="text/javascript">
// this will be processed by all capable browsers
</script>

<script type="text/Jscript">
// this will be processed by IE only
// note capital "J" - it is not a typo,
// this is the Content-Type as programmed into IE
</script>