Hi,
I cannot take the time to comment every one of your remarks ;-) but they
are interesting.
Matt said:
As a doc specifically for their project, I can't comment. But if this doc
were to be morphed into a more general document, I would make the following
observations:
- "new Object()" in code should be discouraged but it's in an example in
2.2.3
- alert(), confirm(), and prompt() have their place and shouldn't
necessarily be avoided in production code
We have a special situation: Our licenses are using a lease-based
system, and the lease is renewed using recurrent web service calls. If
the client leaves an alert open too long, he loses the license (because
the web service calls are blocked). Thus, we forbid using alert in that
project.
- Prefixing variable names to indicate type is Old School, and is
questionable in a non-typed language like JS.
We found it invaluable for JavaScript, *because* it is non typed. For
the records, "systems" hungarian notation is discouraged in our C#
guidelines. We made an exception in JavaScript because we think that it
improves readibility greatly.
- Use XML tags for documenting? I would prefer jsdoc syntax.
The reason why we use XML comment is compatibility with C# code. Our
developers are C# developers, we don't want to confuse them with a new
documentation syntax. The lack of support for inline documentation (à la
intellisense for C# XML doc) is a shame, though.
- Combining variable declaration shouldn't be avoided.
- The comment in 5.2.1 of "A variable ought to be declared within the
smallest possible scope to improve the readability of the code and so that
variables are not unnecessarily allocated" seems misguided. A "var i",
whether at the beginning of a function or declared in a for loop, will still
be allocated:
function() {
var i;
if (false) {
for (var j=0; j<10; j++) { alert('unreachable'); }
}
alert(i);
alert(j);
alert(k);
}
Although I often 'var' variables close to where they are used, it would
probably be a better recommendation to declare them at the top of functions.
We think that declaring the variable near to where it is used improves
readibility especially for C# trained developers. For the records, we
have the same guideline in VB, which is also not scoped.
In general, it's not a bad place to start and a group would be better off
with these conventions than none, IMO. But much could be added to this doc
that would be more practical than variable naming conventions, for example.
I intended to extend my own "Best Practices" document at some point to
include more syntax suggestions like those found in this doc, so this may be
a good starting point.
Yes, but we didn't want to publish a "best practice document". This is a
guidelines document and nothing else. You're more than welcome to
elaborate on it!
Greetings,
Laurent
