Jump to: navigation, search

Difference between revisions of "Horizon/Javascript"

(Created page with "== ****** Under Construction ****** == == Code Style Guidelines == As a project, Horizon adheres to code quality standards. To that end we listed out coding standards and...")
 
(Code Style Guidelines)
Line 4: Line 4:
 
== Code Style Guidelines ==
 
== Code Style Guidelines ==
  
As a project, Horizon adheres to code quality standards.  To that end we listed out coding standards and best practices for the different languages divided into Required, Recommended and Optional sections.  Our main goal is to have code that is readable, maintainable, and reliable.
+
As a project, Horizon adheres to code quality standards.  To that end we listed out coding standards and best practices for the different languages divided into Required, Recommended and Optional sections.  Our main goal in establishing these best practices is to have code that is readable, maintainable, and reliable.
  
 
=== JavaScript ===
 
=== JavaScript ===
 
==== Required: ====
 
==== Required: ====
Code Review Checklist -
+
To start out with here is a checklist of "do's and "don't" that you should always should apply to your code or code you are reviewing.
     * No variables or functions in the global namespace
+
'''Code Review Checklist''' -
     * No commented-out code
+
     * No variables or functions in the global namespace.  There are several reasons, why globals are bad, one being that all JavaScript included in an application runs in the same scope.  Which means that if another script has the same method or variable names they overwrite each.
 +
     * No commented-out code.
 
     * Remove dead code
 
     * Remove dead code
 
     * Avoid HTML and CSS in JS code; use templates and stylesheets
 
     * Avoid HTML and CSS in JS code; use templates and stylesheets
 
     * Comment at top of every file, explaining what it is. Also for methods and variables when meaning is not obvious.
 
     * Comment at top of every file, explaining what it is. Also for methods and variables when meaning is not obvious.
     * Always use var for variables unless its intended for global space
+
     * Always use var for variables unless its intended for global space.    But as mentioned earlier, global variables in general are bad, so unless you have specific reason look for alternatives to using globals.
 
     * Avoid using eval
 
     * Avoid using eval
 
     * Avoid using with
 
     * Avoid using with

Revision as of 17:20, 13 August 2014

****** Under Construction ******

Code Style Guidelines

As a project, Horizon adheres to code quality standards. To that end we listed out coding standards and best practices for the different languages divided into Required, Recommended and Optional sections. Our main goal in establishing these best practices is to have code that is readable, maintainable, and reliable.

JavaScript

Required:

To start out with here is a checklist of "do's and "don't" that you should always should apply to your code or code you are reviewing. Code Review Checklist -

    * No variables or functions in the global namespace.   There are several reasons, why globals are bad, one being that all JavaScript included in an application runs in the same scope.  Which means that if another script has the same method or variable names they overwrite each.
    * No commented-out code.
    * Remove dead code
    * Avoid HTML and CSS in JS code; use templates and stylesheets
    * Comment at top of every file, explaining what it is. Also for methods and variables when meaning is not obvious.
    * Always use var for variables unless its intended for global space.    But as mentioned earlier, global variables in general are bad, so unless you have specific reason look for alternatives to using globals.
    * Avoid using eval
    * Avoid using with
    * Avoid excessive nesting
    * Avoid excessive function chaining
    * Using === as oppose to == for equality check
    * Using DOM fragments as oppose to modifying DOMs each iteration
    * Enclose each JS file inside of a self-executing function. Then use "strict". Like this: (function(){ 'use strict'; ...  The self-executing function keeps the strict scoped to the file, so it does not apply to other JS files in the build.

JSHint improves JavaScript quality. Horizon does not include JSHint in the build for legal reasons, so it is only used during code editing. Therefore, JavaScript developers should configure their editors to use JSHint to warn them of any errors. Instructions for setting up JSHint for Eclipse, Sublime Text, Notepad++ and WebStorm/PyCharm are provided.

Recommended:

Source-code formatting – (or “beautification”) is recommend but should be used with caution. Keep in mind that if you reformat an entire file that was not previously formatted the same way, it will mess up the diff during the code review. It is best to use a formatter when you are working on a new file by yourself, or with others who are using the same formatter. You can also choose to format a selected portion of a file only. Instructions for setting up JSHint for Eclipse, Sublime Text, Notepad++ and WebStorm/PyCharm are provided.

Optional:

AngularJS

Define your angular app under the angular folder (such as horizon.table.js). You can choose to lump them all in one file. If your file is getting too big and readability becomes an issue, consider moving them into the individual folders (filters, directives, etc..)

Separate presentation and business logic. Controllers and Services should not contain DOM references. Directives do. Controllers have view behaviors Services are singletons and contain logic independent of view

Scope - Read-only in from templates, write-only in controllers

Required:

For testability, do not put view logic inside controllers or filters. Put it in directives when necessary.

Recommended:

Since Django already uses {{ }}, use {$ $} instead or {% verbatim %}

Don't use variables like "app" that are at the highest level in the file, when Angular gives an alternative, instead you function chaining.

Put "Ctrl" on the end of a controller name Use these directories: filters, directives, controllers, and templates. When you use the directory name, the file name does not have to include words like "directive" or "filter".

Optional: