Coding guidelines for the ExtJS developers

Introduction

Walking Tree has been using ExtJS for more than 6 years. In addition, being associated with Sencha at training level we do see us responsible for helping the community in using ExtJS in the best possible ways. When we started using ExtJS in 2008-2009, I personally compared it with Perl. Sounds strange!

Yep, Perl is amazingly powerful scripting language. Without appropriate guidelines / structure, it didn’t look so useful.However, if you wrap this under Object Oriented concepts then it looks awesome. Similarly, I personally never thought Javascript will dominate the language world, until we started using ExtJS. The continuous improvement in ExtJS – by community as well as Sencha has strengthened my belief further.

Javascript is a powerful language and ExtJS is a beautiful framework. However, care should be taken to write good clean code. We had our own struggle in the beginning and in that process we also had significant learning. Along the way, we have developed few guidelines, which I thought will be great to share with the community. I am putting these guidelines in this article. In case you do have an input which can improve this then do feel free to contribute.

Declaration and Convention

Variables

Naming Convention

1. Names should be formed from the 26 upper and lower case letters (A .. Z, a .. z), the 10 digits (0 .. 9), and _ (underscore).
   1. Avoid the use of international characters because they may not read well or be understood everywhere.
   2. Do not use $ (dollar sign) or \ (backslash) in names
2. Always begin your variable names with a letter, not “$” or “_”.
3. Use full and meaningful words instead of cryptic abbreviations. Doing so will make your code easier to read and understand. In many cases, it will also make your code self-documenting
4. Keep in mind that the name you choose must not be a keyword or reserved word
5. If the name you choose consists of only one word, spell that word in all lowercase letters
6. Use lowerCamelCase (e.g. calculatedRatio)  notation for variables with more than one word in its name

Variable Declarations

1. All variables should be declared before used.
   1. JavaScript does not require this, but doing so makes the program easier to read and makes it easier to detect undeclared variables that may become implied globals or that may not be initialized but used.
   2. Implied global variables should never be used
   3. Also, the use of global variables must be minimized
2. The var statements should be the first statements in the function body
3. JavaScript does not have block scope, so defining variables in blocks can confuse programmers who are experienced with other C family languages. Define all variables at the top of the function.
4. It is preferred that each variable be given its own line and comment. This is one thing which I see that people start debating, however, I do hate to see multiple variables being declared (and initialized) on the same line.
   1. The variables should be listed in alphabetical order as shown below:
      1. var currentEntry = -1;
      2. var level = 0;

 Class Names

1. The class name follows similar naming convention as variable names – except that they follow UpperCamelCase notation.
2. A class must be defined in its own file and the file name shall exactly match the class name. Use ExtJS structure to give package name for better organisation of files in larger projects.

Event Naming Convention

• The event name must be in all lower cases. We must not use the camelCase convention. For example, onAddCommunication or addCommunication is not good, while the event name addcommunication will be considered good

Using Layout or Similar Potentially Compound Declarations

While declaring the layout for a container ExtJS allows you to use one of the following approaches

or

While the later declaration becomes mandatory, in case you do want to use custom values for the properties, the presence of two separate ways of declarations make it confusing for the beginners. Also, since it doesn’t add too much to the space savings, I personally recommend using the layout config with an explicit type property.

View Models and Data Binding

1. Prefer Using Declarations over procedural calls
   1. While you can use “bind()” method on the component (remember all the components are bindable) to bind a view with its model, it is cleaner to specify bind properties in the declaration itself.
2. Use “deep:true” declaration when you are binding a value with an object/property embedded inside another object
3. When you have derived variables, use formula configuration of the ViewModel. Use get and set function declarations appropriately to support two-way derivation

Form Validation and Submission

1. Use models for validating and submitting the forms and push the field validation logic (including custom validations) inside models
2. Use loadRecord method of the FormPanel instead of setting the form fields individually. Setting individual fields is error prone as and it makes the code look cluttered
3. Instead of using explicit logic to enable/disable a submit button, make use of “formBind: true”

Other Common Tips

1. The “defaults” config allows you to mention the default values that you would like to specify for the child items of a container.
   1. Quite often I see that people don’t use this and instead repeat the same configuration and their values across different child elements.
   2. Further many times people mention “xtype : ‘panel'” when the panel might already be the default xtype for the given item
2. The controllers are only associated with their views (from ExtJS 5 onwards). Hence don’t try to force fit something which may not be directly coming from the view. Otherwise, it will create abstraction and maintainability will be compromised
3. Whenever you are using a component, it will be a good idea to include that into “requires” section to avoid any runtime warning.

Scopes

Correct understanding and usage of “scope” is crucial for effective use of Javascript in general and ExtJS in particular. Pay close attention to the following:

Global Variables

1. Build a habit of always using “var” keyword for declaring variable so that appropriate scope gets considered.
   1. If you don’t use “var” keyword while defining the variable then it is considered as a global variable
   2. The variables declared outside a function is considered in global scope – irrespective of the usage of “var” keyword
   3. These variables are global “window” namespace. For example, the following declarations would result in the same thing, however, the one with “window” namespace being mentioned explicitly is considered a better practice.
      1. var gCompanyName = “Walking Tree”;
      2. window.companyName = “Walking Tree”;
2. If you do want to define global variable then create a separate file and put your variables into that
   • If the global variables can be grouped/categorized then put them under the most suitable category in a JSON object format
     • This is often useful for defining labels, titles, IDs, presets
   • Never hard code strings into program codes, component configurations or templates

this or that

Coming from C++ / Java background, I always found scoping in ExtJS cryptic. The usage of me, this, that, etc by the experienced developers were forcing me to think that there has to be a logic.

Two rules for “this”

1. When a function is executed via a var reference, the default execution context is “window“
2. When a function is executed via an object key, the execution context is “the object“

The following table shows codes in var reference and object key reference:

Following guidelines and simplification of understanding would help:

1. You may like to consider using saving the “this” scope into a different (and smaller) name (e.g. me), which can be considered for minification as well. Some of the cases where it may look very useful are:
   1. When you do have a need for referring to different components from an existing component and write certain logic (e.g. you may like to define an inline handler for an event on an instance of a component). In such cases, the “this” scope would represent the scope related to current component/object, while I will represent the component which created the current component
2. “this” keyword used in the context of var is executed on the window object and when it is executed on an object key then it is in the context of that specific object

Readability Guidelines

1. The unit of indentation must be four spaces.
   1. Use of tabs should be avoided because there still is not a standard for the placement of tabstops. The use of spaces can produce an insignificantly bigger filesize, and that difference is eliminated to a large extent by minification.
2. JavaScript programs should be stored in and delivered as .js files.
3. Avoid lines longer than 80 characters. When a statement will not fit on a single line, it may be necessary to break it.
   1. Place the line break after an operator, ideally after a comma.
   2. A break after an operator decreases the likelihood that a copy-paste error will be masked by semicolon insertion.
   3. The next line should be indented 8 spaces.
4. The comments should be well-written and clear. It shall not duplicate the code statements rather it shall complement the code and put together it shall provide 100% completeness. It is important that comments are kept up-to-date and whenever there is a change in the related code, the comment must ensure that it is still valid and consistent with the changed code.
   1. The comments like i = 0; // Set i to zero, is irrelevant and undesirable.
   2. Generally use line comments (//).
   3. Save block comments (/* */) for formal documentation and for commenting out
5. Blank lines improve readability by setting off sections of code that are logically related
6. Blank spaces should be used in the following circumstances:
   1. A keyword followed by ( (left parenthesis) should be separated by a space.
   2. A blank space should not be used between a function value and its ( (left parenthesis). This helps to distinguish between keywords and function invocations.
   3. All binary operators except. (period) and ( (left parenthesis) and [ (left bracket) should be separated from their operands by a space.
   4. No space should separate a unary operator and its operand except when the operator is a word such as typeof
   5. Each ; (semicolon) in the control part of a for statement should be followed by a space.
   6. Whitespace should follow every, (comma).

Logic and Statements Guidelines

Comparison and Assignment

Lifecycle Guidelines

new operator

1. Use {} instead of new Object()
2. Use [] instead of new Array().
3. For ExtJS objects, you shall use create a method
4. In nutshell, avoid using new.
   1. For dates related objects, you might still be required to use new. However, for other types of data, you shall not be required to use the new operator.

 Controllers & Views

1. Facts to be noticed
   1. While this is a fact, instead of a guideline, it is worth being aware of, while using lifecycle methods of controllers and views.
      1. The views have life cycle methods like – constructor and initComponents and they are called in the following order
         1. constructor
         2. initComponent
      2. The controller has 3 lifecycle methods – init, beforeInit and initViewModel. They are called in the following orders:
         1. beforeInit
         2. init
         3. initViewModel
      3. When combined the view and controller lifecycle methods are executed in the following order
         1. constructor of View
         2. beforeInit of Controller
         3. initComponent of View
         4. init of Controller
         5. initViewModel of Controller

Performance Guidelines

1. Keep DOM as small as possible
   1. Using “deferredRender: true” declaration you can ensure that the tabs of the tabpanel (for that matter any container using the card layout) will be rendered at the time it becomes active. This is pretty helpful when
      1. there is a significant amount of content or
      2. a lot of heavy controls or
      3. there are many tabs and user may access only a few during any given session
   2. Avoid component nesting
      1. Many times people use panel inside the window and make similar mistakes elsewhere, which increases nesting as well as the size of the DOM
2. Ext JS Panels are more powerful (and expensive!) than basic Containers and you may not need them all the time. So specify xtype: ‘container’ to avoid having your application use the default ‘panel’ unless you are sure that you need a panel.
3. Minimize DOM access/manipulation
   1. ExtJS is a component library and one of its main goals is to insulate you from directly manipulating DOM. So, whenever you do have such need, there is nothing wrong in being a little more alert 🙂
      1. Always consider using Sencha classes which wraps the native javascript DOM methods, otherwise, you may end up facing browser compatibility issues
   2. While using the query method, often people use Ext.ComponentQuery.query without root elements. This means that all Components within the document are included in the search and thus the search become costlier.
   3. Depending on the context, consider using container’s “down” or “child” and  component’s “up” method to minimize the number of search components
   4. Avoid using document.getElementById()
   5. Avoid using Ext.getCmp()
4. Avoid usage of hard coded “id” property. While id may seem like giving quick access to the element, it is easier to commit mistakes in enterprise application and often it is very costly to identify and rectify such problems.
   1. In case it is being used, there must be a strong reason to do so and explicit comments must be specified.
   2. Evaluate the possibility of using “itemId” config of components instead
5. Instead of using images for buttons/tabs, make use of glyphs, wherever applicable
6. Make use of object references while accessing an object/property deeply nested inside an object
   1. Specifically, this is extremely important when such properties are getting accessed / used inside a loop
   2. Similarly, when you loop on array size then keep the size calculated outside the loop
   3. The idea is simple – keep computation-heavy code outside the loop
7. Make use of object references while handling events
   1. All the event handler have the component reference being passed as the first parameter of the method. Make use of that in case you need to change anything on the view
   2. Also, in case you do have a need to update some other view/component then specify reference on that component and make use of the lookupReference() method in the controller
8. Must avoid Memory Leaks
   1. Some times developers create a new object and they don’t bother about reusing the already created object. For example, the developer may create a context menu every time the user right clicks. This is a bad practice. Instead, it should be created once and reused whenever possible.
9. Use console.time(“YourTimer”) method to determine how long an operation takes.

General Guidelines

1. Ext.apply Copies all the properties of config to the specified object. Note that if recursive merging and cloning without referencing the original object/array is needed, use Ext.Object.merge instead.
2. You must avoid hard coding of height, width
3. Use arrays when the member names would be sequential integers. Use objects when the member names are arbitrary strings or names
4. Watch out for the extra comma which is not required in your code
5. Never leave debugger statement in a code
6. Never user “eval()”
7. While most of the browsers support Javascript by default, while designing enterprise solutions, you must assume that Javascript may be disabled and accordingly you shall implement the solution
8. Think of your code as a story and make it easier for people to read
9. Use CSS classes to keep the look and feel to the CSS designer. Strictly avoid any programmatic styling which you can achieve through simple CSS selectors and/or inheritances

10. If you find yourself creating lots and lots of HTML in ExtJS, you might be doing something wrong. XTemplate does expect you to put HTML code, and good practice is to keep all such fragments in a common place.

11. Although MVC is still supported in ExtJS, use the new MVVC / MVVM pattern as it separates the concerns really nicely, which is desired for an enterprise level applications

Documentation

Code documentation must be done using JSDuck annotations. Following are the minimal documentation requirement:

1. Every class must be documented
2. Every public and protected property of a class must be documented along with an example value. The document must indicate if the property is mandatory or optional. The default value must be specified for the optional properties.
3. Every public and protected method of a class must be documented
4. Events fired by a class must be documented along with the parameters that will be passed to a listener
5. JSDuck document must be generated from the documented code.

Summary

In this blog, I have tried to put a consolidated set of rules/guidelines that you would like yourself and your team to follow. I hope this article helps you write better code and your productivity increases significantly.  While this article will help in bridging the knowledge gap, usage of JS Lint or equivalent tool will definitely add more value. I am definitely considering this article as a running document and it will change over a period. Feel free to shoot your comment and suggestions!

Walking Tree is a Sencha Service and Training Partner. We would love to help you in making effective use of the framework.

You can reach us by filling in the following form:

Reference

• http://javascript.crockford.com/code.html
• https://vimeo.com/79436259
• http://www.htmlgoodies.com/beyond/javascript/variable-naming-conventions-in-javascript.html
• http://dailyjs.com/2012/07/23/js101-scope/
• http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
• https://developer.chrome.com/devtools/docs/console-api