JavaScript guidelines published

[Laurent Bugnion [MVP]]

Hi group,

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_Guidelines.pdf

Please note the following:

* The purpose of publishing this document on the World Wide Web is to
promote and encourage consistent practices in the JavaScript programming
community.

* We publish this document as information only. Siemens will not accept
any responsibility regarding its content.

* The guidelines are recommendations based on our experience, and may or
may not make sense in the context of a different company, or a different
project. Their intent is to be a source of inspiration for other
JavaScript developers, and nothing more.

* The guidelines are dated 20th of April 2004, which is quite some time
ago. I think that most of the recommendations are still valid, but of
course additions can be made.

HTH,
Laurent

 

[Matt Kruse]

In agreement with the head of our R&D department, I published my
firm's JavaScript Coding Guidelines.

Fantastic!
Although I don't agreement with all of the conventions, I think that
publishing documents like this could give someone a good place to start from
in trying to make their coding more consistent, and in the end that will be
nothing but positive. Thank you for sharing.

Do you use any tool to check that js source files adhere to these standards?
What positive impact has this document had in your work environment - do
people follow it? Is it enforced? Was there any push back against it?

 

[Laurent Bugnion [MVP]]

Matt,

Fantastic!
Although I don't agreement with all of the conventions, I think that
publishing documents like this could give someone a good place to start from
in trying to make their coding more consistent, and in the end that will be
nothing but positive. Thank you for sharing.

To be honest, I also don't agree with all of them (though I strictly
adhere to them in my job, and use my own set in my private projects).
Guidelines like this are a teamwork, and sometimes we had to compromise.

Do you use any tool to check that js source files adhere to these standards?

We don't, but we used code reviews, where one of the criteria tested was
the enforcement of these guidelines.

What positive impact has this document had in your work environment - do
people follow it?

Yes, very much so. In fact, the situation was relatively easy, because
most of my coworkers didn't have much (if any) experience with
JavaScript, so they kind of believed me when I told them that this was
the way to go ;-) Seriously, the people I worked with (and coordinated)
in that project did an excellent job. For the records, the application
is an ASP.NET web application used for building automation. The server
part relies on an existing unmanaged C++ product which we extended with
..NET code. We rely on .NET remoting for communication between the web
server and the C++ server, and make quite intensive use of web services
between the client and the web server. We already had the web
application up and running for more than 2 weeks in intensive test
conditions without any trouble. We wrote about 15000 lines of code (not
counting generated code, for which we wrote a JavaScript cross compiler).

The development time was about 1.5 years

Is it enforced? Was there any push back against it?

No push back. All the developers are professionals with many years
experience in other languages (C++, Java, C# mostly) and all of them
understand the value of guidelines.

Greetings,
Laurent

 

[-Lost]

Hi group,

In agreement with the head of our R&D department, I published my firm's JavaScript
Coding Guidelines. I work for Siemens Building Technologies. We developed these
guidelines for a web application project in 2004, based on our C# guidelines.

http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_Guidelines.pdf

Awesome! This has been a long time coming and quite frankly I am glad to see it.

Thanks, Laurent.

-Lost

 

[-Lost]

Fantastic!
Although I don't agreement with all of the conventions, I think that publishing
documents like this could give someone a good place to start from in trying to make
their coding more consistent, and in the end that will be nothing but positive. Thank
you for sharing.

Really? What conventions do you not agree with and why?

I would love to keep a running tally of all the amendments "the JavaScript gurus" like
yourself, <and you know who you are guys>, think should be modified in this document.

I would be glad to publish the revisions in whatever format was deemed acceptable
(assuming Laurent does not have the time to update it himself). I figured it could be a
separate project unto the Siemens guidelines.

-Lost

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]>, Mon, 5

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

Good, largely. But :-

Does Siemens not use ISO 8601 date format? "08.11.2004" is a form not
commonly used in English, either.

3-101, 4-103 are bad choices <g>.

3-204 - that's nothing : in Pascal one can do
const true = false ; false = not true ;

4-101 - often disregarded elsewhere. I suggest that each file should
also have a trailer block, as a guard against accidental incomplete
copies. "// End" would suffice.

4-102 - The meaning is clear, and good; but the statement is defective.

11-203 - How about continuation lines (where FORTRAN would use a C)?

Especially for the benefit of those using slow links, ISTM worth
indicating size by a link to a PDF. Some PDFs are big!. Yours is 70kB.


Could/should the document be cited in the newsgroup FAQ?

 

[Matt Kruse]

Really? What conventions do you not agree with and why?

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

- Prefixing variable names to indicate type is Old School, and is
questionable in a non-typed language like JS.

- Use XML tags for documenting? I would prefer jsdoc syntax.

- 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.

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.

 

[VK]

Hi group,

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

<http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_Guidelines.pdf>

Thanks for that.

 

[RobG]

Hi group,

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_...

As others have said, a very good start. Of course I have some
personal dislikes here and there but none worth arguing over.

Chapter 6 Flow Control references another document that isn't
provided. Any chance you can make that available too?

 

[Douglas Crockford]

Hi group,

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_Guidelines.pdf

5.2.1 Rec. 5-101 Declare and initialize variables close to where they are used.

This would be good advice for languages with block scope. JavaScript does not
have block scope, only function scope, so the recommendation should be to
declare variables at the beginning of the function.

Also see http://javascript.crockford.com/code.html

 

[Peter Michaux]

5.2.1 Rec. 5-101 Declare and initialize variables close to where they are used.

This would be good advice for languages with block scope. JavaScript does not
have block scope, only function scope, so the recommendation should be to
declare variables at the beginning of the function.

Also seehttp://javascript.crockford.com/code.html

Dean Edwards made a point against declaring at the top of a function.
When all the variables are at the top and some middle section of the
function is refactored to another location, the variable declarations
don't go with the refactored code. Then the variables are implicit
globals.

Peter

 

[Matt Kruse]

Dean Edwards made a point against declaring at the top of a function.
When all the variables are at the top and some middle section of the
function is refactored to another location, the variable declarations
don't go with the refactored code. Then the variables are implicit
globals.

I agree for variables that are used only within "block scope". If the code
is ever copied, the lack of 'var' declarations might cause a problem.

Since Javascript doesn't care if you declare a variable multiple times with
'var', I do it every time in loops like:
for (var i=0; i<len; i++)

For variables that are used throughout a function, it would be a better
recommendation to declare them at the top rather than when they are first
used.

 

[Lee]

Peter Michaux said:

Dean Edwards made a point against declaring at the top of a function.
When all the variables are at the top and some middle section of the
function is refactored to another location, the variable declarations
don't go with the refactored code. Then the variables are implicit
globals.

A function shouldn't be so large and complex that some middle section
of it would be pulled out, or if it is, the declarations should still
be visible in the same screen full of text, and the person yanking
them should take responsibility for including the declarations.


--

 

[Dr J R Stockton]

- Prefixing variable names to indicate type is Old School, and is
questionable in a non-typed language like JS.

Bearing in mind that, in the context given, code is written to be read
as well as executed, ISTM that where a variable is intended to be of
only one type during its lifetime it could be well to indicate that
thusly, as an aid to readers determining whether the code which was
written is the code which ought to have been written.

One might also say that, where the value of a variable will only be used
within a very short amount of code, it may be given a very short and
meaningless name.

Example : L = List.length ; for (J=0; J<L; J++) Total += List[J] ;

- Combining variable declaration shouldn't be avoided.

Should not be forbidden. In code about Hamiltonians,
var w, x, y, z ;
makes sense. But often it is reasonable to avoid combinations.

- 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:

But that's not important for the readability of the code.
Unfortunately, AFAIR, there's no un-declare.

In fact, Algol was good there; if a variable J was going to be needed
only in a short part of the code, one could surround that part with
begin var J : integer ; ... end ; . If the next section needed
var X : real ; then the compiler probably would make J & X share
storage, for what it's worth.

 

[Mister Joe]

Hi group,

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_...

Please note the following:

* The purpose of publishing this document on the World Wide Web is to
promote and encourage consistent practices in the JavaScript programming
community.

* We publish this document as information only. Siemens will not accept
any responsibility regarding its content.

* The guidelines are recommendations based on our experience, and may or
may not make sense in the context of a different company, or a different
project. Their intent is to be a source of inspiration for other
JavaScript developers, and nothing more.

* The guidelines are dated 20th of April 2004, which is quite some time
ago. I think that most of the recommendations are still valid, but of
course additions can be made.

HTH,
Laurent
--
Laurent Bugnion [MVP ASP.NET]
Software engineering, Blog:http://www.galasoft-LB.ch
PhotoAlbum:http://www.galasoft-LB.ch/pictures
Support children in Calcutta:http://www.calcutta-espoir.ch

Just out of curiosity what alternatives to alert(), confirm() and
prompt() do you guys use in your production code

 

[-Lost]

Hi group,

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_...

Please note the following:

* The purpose of publishing this document on the World Wide Web is to
promote and encourage consistent practices in the JavaScript programming
community.

* We publish this document as information only. Siemens will not accept
any responsibility regarding its content.

* The guidelines are recommendations based on our experience, and may or
may not make sense in the context of a different company, or a different
project. Their intent is to be a source of inspiration for other
JavaScript developers, and nothing more.

* The guidelines are dated 20th of April 2004, which is quite some time
ago. I think that most of the recommendations are still valid, but of
course additions can be made.

HTH,
Laurent
--
Laurent Bugnion [MVP ASP.NET]
Software engineering, Blog:http://www.galasoft-LB.ch
PhotoAlbum:http://www.galasoft-LB.ch/pictures
Support children in Calcutta:http://www.calcutta-espoir.ch

Just out of curiosity what alternatives to alert(), confirm() and
prompt() do you guys use in your production code

I wondered that for a moment as well. My guesses:

alert() is normally (well, for me anyway) used during debugging, in fact it is easier to
debug with alert than it is anything else. Therefore no need for alert() in production
code.

confirm() and prompt() could both take the guise of forms if user input is at all
necessary. For example, if I needed to ask you a serious of demographic questions, what
would you rather endure: 30 prompts or confirms or a nicely formatted display of text
inputs, radios, or check boxes? I definitely think the latter.

So, there is my $0.02.

-Lost

 

[-Lost]

Sorry! I should have snipped Laurent's signature.

*shakes finger at Mister Joe*

-Lost

 

[Peter Michaux]

Hi group,

In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.

http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_...

Thanks for getting permission to share this.

Peter

 

[Peter Michaux]

One might also say that, where the value of a variable will only be used
within a very short amount of code, it may be given a very short and
meaningless name.

Example : L = List.length ; for (J=0; J<L; J++) Total += List[J] ;

I agree completely. I use very short names just like this to point out
the short-lived nature of the variable.

In fact, Algol was good there; if a variable J was going to be needed
only in a short part of the code, one could surround that part with
begin var J : integer ; ... end ; . If the next section needed
var X : real ; then the compiler probably would make J & X share
storage, for what it's worth.

JavaScript 1.7 let statement is similar for defining block scope. Not
the same as Algol but there you go.

Peter

 

[Peter Michaux]

Hi group,
In agreement with the head of our R&D department, I published my firm's
JavaScript Coding Guidelines. I work for Siemens Building Technologies.
We developed these guidelines for a web application project in 2004,
based on our C# guidelines.
http://www.galasoft-lb.ch/myjavascript/Siemens_SBT_JavaScript_Coding_...
Please note the following:
* The purpose of publishing this document on the World Wide Web is to
promote and encourage consistent practices in the JavaScript programming
community.
* We publish this document as information only. Siemens will not accept
any responsibility regarding its content.
* The guidelines are recommendations based on our experience, and may or
may not make sense in the context of a different company, or a different
project. Their intent is to be a source of inspiration for other
JavaScript developers, and nothing more.
* The guidelines are dated 20th of April 2004, which is quite some time
ago. I think that most of the recommendations are still valid, but of
course additions can be made.
HTH,
Laurent
--
Laurent Bugnion [MVP ASP.NET]
Software engineering, Blog:http://www.galasoft-LB.ch
PhotoAlbum:http://www.galasoft-LB.ch/pictures
Support children in Calcutta:http://www.calcutta-espoir.ch

Just out of curiosity what alternatives to alert(), confirm() and
prompt() do you guys use in your production code

I wondered that for a moment as well. My guesses:

alert() is normally (well, for me anyway) used during debugging, in fact it is easier to
debug with alert than it is anything else.

console.log in Safari and in Firefox with Firebug is at least as easy
and I think easier. It saves having to click to close the alert all
the time. Firebug now supplies a JS file to emulate this behavior in
other browsers. I haven't tried that however.

Peter