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

layout : 'vbox'

or


layout : {
    type : 'vbox',
    align : 'middle'
}

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 to use layout config with 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 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 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 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 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 following declarations would result into 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 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

Following table shows codes in var reference and object key reference:


var doSomething  = function() {
    console.log(this);
};

doSomething();
// "this" is the "window" object


var animal = { 
    type : 'human',
    getType : function() {
        console.log(this);
        return this.type;
    }
};

animal.getType();
// "this" is the "animal" object



var getAnimalType = animal.getType;
getAnimalType();
// "this" is the "window" object 

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 case 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 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 me will represent the component which created the current component
  2. this” keyword used in the context of var is executed on 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 a insignificantly bigger filesize, and that difference is eliminated to 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

  1. Use explicit equality comparators (ie “===”) over coerced comparators (ie “==”)
  2. Use explicit inequality comparators (ie “!==”) over coerced comparators (ie “!=”)
  3. Use shortcuts for default value assignment, which make your code more faster as well as more readable. For example below assignment looks much cleaner
    1. var greeting = args.greeting || “Good day”;
  4. For the compound statements, the enclosed statements should be indented four spaces
    1. The { (left curly brace) should be at the end of the line that begins the compound statement.
      The } (right curly brace) should begin a line and be indented to align with the beginning of the line containing the matching { (left curly brace).
    2. Braces should be used around all statements, even single statements, when they are part of a control structure, such as an if or for statement. This makes it easier to add statements without accidentally introducing bugs.
      1.  
        if(someVariableExists)
            x = false;
            anotherFunctionCall();
        
        // Above code is equivalent to below code
        if(someVariableExists) {
            x = false;
        }
        
        anotherFunctionCall();
        
        // While the developer might have wanted to include this method inside if block
        
  5. In a simple comparison operator many times people end up using if-else statement or tertiary operator to eventually return a true / false value based on comparing the parameter(s). In such cases returning the result of the conditional evaluation is the best thing to do.
    1.  
      compareParameters : function( firstParam, secondParam ) {
          return ( firstParam > secondParam );
      }
      
      // Notice the braces around the conditional statement, which is used for increasing readability.
      

 

 

Logging and Tracing

We often see developers using “console.log” in their application and – thats it. While this may be okay during development and test build, a good packaging tool might remove it from the minified / production ready code. Hence it is important to know the available options and their level and use them appropriately. Console support various logging level and here are some of the key ones

  1. info
  2. debug
  3. log
  4. warn
  5. error

The last two must be used as required to be able to diagnose the problem in production environment.

Further, these methods allows you to mention parameters in different formats as arguments. However, often developers use the concatenation operators to create a string. This is a bad practice. Following is a sample example of how an error logging should be taken care:

 
console.error("Error: %s (%i)", "Server is  not responding:", 500);

Statements

  • Each line should contain at most one statement.
  • Put a ; (semicolon) at the end of every simple statement.
    • Note that an assignment statement which is assigning a function literal or object literal is still an assignment statement and must end with a semicolon.

 

Lifecycle Guidelines

new operator

  1. Use {} instead of new Object()
  2. Use [] instead of new Array().
  3. For ExtJS objects, you shall use create 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 new operator.

 Controllers & Views

  1. Facts to be noticed
    1. While this is a fact, instead of 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 following order
        1. constructor
        2. initComponent
      2. The controller have 3 lifecycle methods – init, beforeInit and initViewModel. They are called in following orders:
        1. beforeInit
        2. init
        3. initViewModel
      3. When combined the view and controller lifecycle methods are executed in 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 “: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 few during any given session
    2. Avoid component nesting
      1. Many times people use panel inside window and make similar mistakes elsewhere, which increases nesting as well as 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 goal 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 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 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 a 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 possibility of using “itemId” config of components instead
  5. Instead of using images for buttons / tabs, make use of glyps, 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. 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 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, developer may create a context menu every time 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 are 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 programatic 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 a 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. Document must indicate if the property is mandatory or optional. 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 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 following form:

 

Reference

 

Alok is co-founder of Walking Tree, a company which acts as a product engineering team of the customers across the globe and delivers end-to-end products / solutions to ensure "Great Experience". Walking Tree provides Design, Development, QA, Maintenance and Support, Consulting, Training and Skill Augmentation services around Ext JS, Sencha Touch, Angular JS, Xamarin, Native Android, Native iOS, MongoDB, Cassandra, Hadoop, Pentaho, etc. | Twitter

Tagged with: , , , , ,
Posted in Sencha ExtJS

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

We Have Moved Our Blog!

We have moved our blog to our company site. Check out https://walkingtree.tech/index.php/blog for all latest blogs.

Sencha Select Partner Sencha Training Partner
Xamarin Authorized Partner
Do More. With Sencha.

Recent Publication
%d bloggers like this: