Commit d5d14455 authored by Marco Mariani's avatar Marco Mariani

docs: added complex_queries, developers, gid_storage, naming_conventions

parent e85c91a2
...@@ -222,8 +222,112 @@ JSON Schemas and Grammar ...@@ -222,8 +222,112 @@ JSON Schemas and Grammar
Below you can find schemas for constructing complex queries Below you can find schemas for constructing complex queries
* `Complex Queries JSON Schema <http://www.j-io.org/jio-Complex.Queries.JSON.Schema>`_ * Complex Queries JSON Schema:
* `Simple Queries JSON Schema <http://www.j-io.org/jio-Simple.Queries.JSON.Schema>`_
* `Complex Queries Grammar <http://www.j-io.org/jio-Complex.Queries.Grammar>`_ .. code-block:: javascript
{
"id": "ComplexQuery",
"properties": {
"type": {
"type": "string",
"format": "complex",
"default": "complex",
"description": "The type is used to recognize the query type."
},
"operator": {
"type": "string",
"format": "(AND|OR|NOT)",
"required": true,
"description": "Can be 'AND', 'OR' or 'NOT'."
},
"query_list": {
"type": "array",
"items": {
"type": "object"
},
"required": true,
"default": [],
"description": "query_list is a list of queries which can be in serialized format of in object format."
}
}
}
* Simple Queries JSON Schema:
.. code-block:: javascript
{
"id": "SimpleQuery",
"properties": {
"type": {
"type": "string",
"format": "simple",
"default": "simple",
"description": "The type is used to recognize the query type."
},
"operator": {
"type": "string",
"default": "=",
"format": "(>=?|<=?|!?=)",
"description": "The operator used to compare."
},
"id": {
"type": "string",
"default": "",
"description": "The column id."
},
"value": {
"type": "string",
"default": "",
"description": "The value we want to search."
}
}
}
* Complex Queries Grammar::
search_text
: and_expression
| and_expression search_text
| and_expression OR search_text
and_expression
: boolean_expression
| boolean_expression AND and_expression
boolean_expression
: NOT expression
| expression
expression
: ( search_text )
| COLUMN expression
| value
value
: OPERATOR string
| string
string
: WORD
| STRING
terminal:
OR -> /OR[ ]/
AND -> /AND[ ]/
NOT -> /NOT[ ]/
COLUMN -> /[^><= :\(\)"][^ :\(\)"]*:/
STRING -> /"(\\.|[^\\"])*"/
WORD -> /[^><= :\(\)"][^ :\(\)"]*/
OPERATOR -> /(>=?|<=?|!?=)/
LEFT_PARENTHESE -> /\(/
RIGHT_PARENTHESE -> /\)/
ignore: " "
...@@ -21,7 +21,7 @@ plus the storages and dependencies you need and you will be good to go. ...@@ -21,7 +21,7 @@ plus the storages and dependencies you need and you will be good to go.
Naming Conventions Naming Conventions
------------------ ------------------
All the code follows this `Javascript Naming Conventions <http://www.j-io.org/Javascript-Naming_Conventions>`_. All the code follows this :ref:`Javascript Naming Conventions <naming-conventions>`.
How to design your own jIO Storage Library How to design your own jIO Storage Library
------------------------------------------ ------------------------------------------
......
...@@ -97,7 +97,7 @@ metadata can contain several values. Example: ...@@ -97,7 +97,7 @@ metadata can contain several values. Example:
// or // or
"key": ["value1", "value2"], "key": ["value1", "value2"],
// or // or
"key": {"attribute name": "attribute value", "content": "value'}, "key": {"attribute name": "attribute value", "content": "value"},
// or // or
"key": [ "key": [
{"scheme": "DCTERMS.URI", "content": "http://foo.com/bar"}, {"scheme": "DCTERMS.URI", "content": "http://foo.com/bar"},
......
...@@ -19,6 +19,7 @@ Contents: ...@@ -19,6 +19,7 @@ Contents:
complex_queries complex_queries
metadata metadata
developers developers
naming_conventions
authors authors
license license
......
.. role:: js(code)
:language: javascript
.. _naming-conventions:
JavaScript Naming Conventions
=============================
This document defines JavaScript naming conventions, which are split into essential, coding and naming conventions.
Essential Conventions
---------------------
Essential conventions include generic patterns that should be adhered in order to write *readable*, *consistent* and *maintainable* code.
Minimizing Globals
^^^^^^^^^^^^^^^^^^
Variable declarations should always be made using *var* to not declare them as
global variables. This avoids conflicts from using a variable name across
different functions as well as conflicts with global variables declared by 3rd
party plugins.
Good Example
.. code-block:: javascript
function sum(x, y) {
var result = x + y;
return result;
}
Bad Example
.. code-block:: javascript
function sum(x, y) {
// missing var declaration, implied global
result = x + y;
return result;
}
Use JSLint
^^^^^^^^^^
`JSLint <http://www.jslint.com/>`_ is a quality tool that inspects code and warns
about potential problems. It is available online and can also be integrated
into several development environments, so errors will be highlighted when
writing code.
Before validating your code in JSLint, you should use a code
beautifier to fix basic syntax errors (like indentation) automatically. There
are a number of beautifiers available online. The following seem to be the best
working:
* `JSbeautifier.org <http://jsbeautifier.org/>`_
* `JS-Beautify <http://alexis.m2osw.com/js-beautify/>`_
Here, javascript sources have to begin with this header: :js:`/*jslint indent: 2,
maxlen: 80, nomen: true */`, which means it uses two spaces indentation, 80
maximum characters by line and allow the use of '_' as first variable name
character. Other JSLint options can be added in sub functions if necessary;
Allowed options are:
* ``ass: true`` if assignment should be allowed outside of statement position.
* ``bitwise: true`` if bitwise operators should be allowed.
* ``continue: true`` if the continue statement should be allowed.
* ``newcap: true`` if Initial Caps with constructor function is optional.
* ``regexp: true`` if ``.`` and ``[^...]`` should be allowed in RegExp literals. They match more material than might be expected, allowing attackers to confuse applications. These forms should not be used when validating in secure applications.
* ``unparam: true`` if warnings should not be given for unused parameters.
Coding Conventions
------------------
Coding conventions include generic patterns that ensure that written code adheres to certain formatting conventions.
Uses two-space indentation
^^^^^^^^^^^^^^^^^^^^^^^^^^
Tabs and 2-space indentation are being used equally. Since a lot of errors on
JSLint often result from mixed use of space and tab using 2 spaces throughout
prevents these errors up front.
Good Example
.. code-block:: javascript
function outer(a, b) {
var c = 1,
d = 2,
inner;
if (a > b) {
inner = function () {
return {
"r": c - d
};
};
} else {
inner = function () {
return {
"r": c + d
};
};
}
return inner;
}
Bad Example
.. code-block:: javascript
function outer(a, b) {
var c = 1,
d = 2,
inner;
if (a > b) {
inner = function () {
return {
r: c - d
}}}};
Using shorthand for conditional statements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An alternative for using braces is the shorthand notation for conditional
statements. When using multiple conditions, the conditional statement can be
split on multiple lines.
Good Example
.. code-block:: javascript
// single line
var results = test === true ? alert(1) : alert(2);
// multiple lines
var results = (test === true && number === undefined ?
alert(1) : alert(2));
var results = (test === true ?
alert(1) : number === undefined ?
alert(2) : alert(3));
Bad Example
.. code-block:: javascript
// multiple conditions
var results = (test === true && number === undefined) ?
alert(1) :
alert(2);
Opening Brace Location
^^^^^^^^^^^^^^^^^^^^^^
Always put the opening brace on the same line as the previous statement.
Bad Example
.. code-block:: javascript
function func()
{
return
{
"name": "Batman"
};
}
Good Example
.. code-block:: javascript
function func () {
return {
"name": "Batman"
};
}
Closing Brace Location
^^^^^^^^^^^^^^^^^^^^^^
The closing brace should be on the same indent as the original function call.
Bad Example
.. code-block:: javascript
function func() {
return {
"name": "Batman"
};
}
Good Example
.. code-block:: javascript
function func() {
return {
"name": "Batman"
};
}
Function Declaration Location
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Non anonymous functions should be declared before use.
Bad Example
.. code-block:: javascript
// [...]
return {
"namedFunction": function namedFunction() {
return;
}
};
Good Example
.. code-block:: javascript
// [...]
function namedFunction() {
return;
}
return {
"namedFunction": namedFunction
};
Naming Conventions
------------------
Naming conventions include generic patterns for setting names and identifiers throughout a script.
Constructors
^^^^^^^^^^^^
A constructor function starting with new should always start with a capital letter
.. code-block:: javascript
// bad example
var test = new application();
// good example
var test = new Application();
Methods/Functions
^^^^^^^^^^^^^^^^^
A method/function should always start with a small letter.
.. code-block:: javascript
// bad example
function MyFunction() {...}
// good example
function myFunction() {...}
TitleCase, camelCase
^^^^^^^^^^^^^^^^^^^^
Follow the camel case convention, typing the words in lower-case, only capitalizing the first letter in each word.
.. code-block:: javascript
// Good example constructor = TitleCase
var test = new PrototypeApplication();
// Bad example constructor
var test = new PROTOTYPEAPPLICATION();
// Good example functions/methods = camelCase
myFunction();
calculateArea();
// Bad example functions/methods
MyFunction();
CalculateArea();
Variables
^^^^^^^^^
Variables with multiple words should always use an underscore between words.
.. code-block:: javascript
// bad example
var deliveryNote = 1;
// good example
var delivery_note = 1;
Confusing variable names should end with the variable type.
Example
.. code-block:: javascript
// implicit type
var my_callback = doSomething();
var Person = require("./person");
// confusing names + var type
var do_something_function = doSomething.bind(context);
var value_list = getObjectOrArray();
// value_list can be an object which can be cast into an array
To use camelCase, when sometimes it is impossible to declare a function directly, the function variable name should match some patterns which shows that it is a function.
.. code-block:: javascript
// good example
var doSomethingFunction = function () { ... };
// or
var tool = {"doSomething": function () { ... }};
// bad example
var doSomething = function () { ... };
Element Classes and IDs
^^^^^^^^^^^^^^^^^^^^^^^
JavaScript can access elements by their ID attribute and class names. When
assigning IDs and class names with multiple words, these should also be
separated by an underscore (same as variables).
Example
.. code-block:: javascript
// bad example
test.setAttribute("id", "uniqueIdentifier");
// good example
test.setAttribute("id", "unique_identifier");
Discuss - checked with jQuery UI/jQuery Mobile, they don't use written name conventions, only
* events names should fit their purpose (pageChange for changing a page)
* element classes use “-” like in ui-shadow
* "ui" should not be used by third party developers
* variables and events use lower camel-case like pageChange and activePage
Underscore Private Methods
^^^^^^^^^^^^^^^^^^^^^^^^^^
Private methods should use a leading underscore to separate them from public methods (although this does not technically make a method private).
Good Example
.. code-block:: javascript
var person = {
"getName": function () {
return this._getFirst() + " " + this._getLast();
},
"_getFirst": function () {
// ...
},
"_getLast": function () {
// ...
}
};
Bad Example
.. code-block:: javascript
var person = {
"getName": function () {
return this.getFirst() + " " + this.getLast();
},
// private function
"getFirst": function () {
// ...
}
};
No Abbreviations
^^^^^^^^^^^^^^^^
Abbreviations should not be used to avoid confusion
Good Example
.. code-block:: javascript
// delivery note
var delivery_note = 1;
Bad Example
.. code-block:: javascript
// delivery note
var del_note = 1;
No Plurals
^^^^^^^^^^
Plurals should not be used when assigning names
.. code-block:: javascript
// good example
var delivery_note_list = ["one", "two"];
// bad example
var delivery_notes = ["one", "two"];
Use Comments
^^^^^^^^^^^^
Should be used with reason but include enough information so that a reader can get a first grasp of what a part of code is supposed to do.
Good Example
.. code-block:: javascript
var person = {
// returns full name string
"getName": function () {
return this._getFirst() + " " + this._getLast();
}
};
Bad Example
.. code-block:: javascript
var person = {
"getName": function () {
return this._getFirst() + " " + this._getLast();
}
};
Documentation
^^^^^^^^^^^^^
You can use `YUIDoc <http://yuilibrary.com/projects/yuidoc>`_ and their custom comment
tags together with Node.js to generate the documentation from the script file
itself. Comments will look something like this:
Good Example
.. code-block:: javascript
/**
* Reverse a string
*
* @param {String} input_string String to reverse
* @return {String} The reversed string
*/
function reverse(input_string) {
// ...
return output_string;
};
Bad Example
.. code-block:: javascript
function reverse(input_string) {
// ...
return output_string;
};
Additional Readings
-------------------
Resources, additional reading materials and links used
* `Javascript Patterns <http://shop.oreilly.com/product/9780596806767.do>`_, main ressource used.
* `JSLint <http://www.jslint.com/>`_, code quality.
* `YUIDoc <http://yuilibrary.com/projects/yuidoc>`_, generate documentation from code.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment