JavaScriptGuidelines

JavaScript Guidelines

Files

A JavaScript file should start with a copyright header of this form (same as Java files):

/*

 * Copyright 2011-2014 Saint Louis University. Licensed under the
 * Educational Community License, Version 2.0 (the "License"); you may
 * not use this file except in compliance with the License. You may
 * obtain a copy of the License at
 *
 * http://www.osedu.org/licenses/ECL-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an "AS IS"
 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */

While many JavaScript files may be needed during development, these should be consolidated and minified where appropriate. In single page applications, all local code should be delivered in one call, in plugin or diverse applications, a more modular approach may be reasonable.

Libraries

Libraries may fall into a variety of categories, but in every case a hosted version is preferred with a local backup if necessary. When possible, a minified version should be used.

External Libraries

When choosing an external library several conditions must be met:

1. The file is tested and established: any developer putting the responsibility of functionality onto third-party code must be prepared to defend the need and maintainability of the choice
2. Most of the library is needed: including an entire library for a minor piece of functionality puts too much of a burden on the end user and may affect maintainability if it is later dropped from the core development
3. There are no licensing conflicts: while rarely a problem, some 'public' libraries are released with specific terms that will not allow the free incorporation into our projects

Internal Libraries

It is often the case that we will want to reuse important pieces of code. While it is important that developers design their code with the general case in mind it is imperative that the second developer to notice the reusable nature of the code and build out the library at that time. If time does not allow for the general case to be retroactively implemented right away, the work should be scheduled.

As library use continues, provisions should be made for generic hosting of these shared libraries.

Snippets

Any time a snippet or piece of another's code is included in CDH code, it must be cited clearly and used with permission

When an entire library is not needed or a piece of existing code needs to be re-purposed without being extracted to a separate file, a well-cited snippet may be appropriate. The beginning and end of this inclusion is important, since the snippet should be regarded as read-only with configuration and over-riding changes made outside of the borrowed code.

Preferred Libraries

Some JavaScript libraries have already been used and proven in CDH projects. Whenever possible, the most up-to-date version of the library should be used at the time of release.

• jQuery (jquery.com) - Popular and widely used library which focuses on imperative development, especially in DOM selection and manipulation. jQuery excels in cross-browser support for common functions and graphic manipulation. AJAX support with callbacks built in for success, failure, and completion.
• jQueryUI - extends jQuery to include a lot of popular interactions and widgets. This library allows for a host of themes as well which, while not ideal in a custom project, may assist in horizontal or throwaway prototyping.
• AngularJS (https://angularjs.org) - Honest MVC structure out of Google focuses on declarative development and separates data manipulation from display well. Allows for the easy development of reusable directives or custom elements and attributes and very compact, readable HTML code.
• AngularUI (http://angular-ui.github.io/) - extends AngularJS with community submitted interactions and custom directives and modules. Care should be taken that anything used is properly vetted as this collection is community moderated.

General Syntax and Conventions

https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
Use the Google style guide as a foul pole for most work. As we develop exceptions to these rules, we can include them here.

Variables

In every case, attaching a variable to the global scope is irresponsible. Creating a global namespace object to pile variables under is often evidence of poor structure, but still preferable to true globals.

Variable names are camel-case, starting with a lower-case letter.

Where part of a name is an abbreviation, it is all upper-case.
e.g. editionID, not editionId; getURL, not getUrl

Member variables get spelled out in full.
e.g. currentEdition, not curEdition

Local variables and parameters can (and should) use shorter names.
e.g. edID for a local variable holding an edition ID

Constants & Enums

Use of static final variables as constants is encouraged.

Constant names and enum values are all upper-case, with components separated by underscores.
e.g. CONFIRMATION_PENDING

Comments

Yes. JSDoc comments in particular.

During project development, there may be the need for bookmark comments. These should be limited to those that NetBeans can create action items from such as TODO and FIXME. Process comments may be used to erect a skeleton for pending code, but obvious comments (e.g., "Increment and repeat") should be removed before public release.

Keep in mind that some of these comments will be visited in versioning or accidentally released in the final code, so while everything may not be professional, it should at least be kept unoffensive and impersonal.

Logging and Messages

For debugging, it may be helpful at times to put in lines for console.log(), but there is rarely a time when these lines should survive the final code cleanup. For advanced user information, throwing an error may be a more accurate action.

If a message is frequently needed for the user in a modal or onscreen, consider generalizing the messaging and avoid the use of alert()s, prompt()s, and confirm()s in the final product.