# NativeScript Modules Coding Convention

## Linting

We use [TSLint](https://palantir.github.io/tslint/) for linting. Rules are defined in `build/tslint.json`.
Run the tslint from the root of the repo with:

```bash
npm run tslint
```

## Tabs vs Spaces

Use 4 spaces indentation.

## Line length

Try to limit your lines to 80 characters.

## Semicolons, statement Termination

Always use semicolons where it is appropriate.

*Right:*

```TypeScript
let x = 1;
```

*Wrong:*

```TypeScript
let x = 1
```

## Quotes

Use double quotes for strings:

*Right:*

```TypeScript
let foo = "bar";
```

*Wrong:*

```TypeScript
let foo = 'bar';
```

## Braces

Your opening braces go on the same line as the statement.

*Right:*

```TypeScript
if (true) {
    console.log("winning");
}
```

*Wrong:*

```TypeScript
if (true)
{
    console.log("losing");
}
```

Also, notice the use of whitespace before and after the condition statement.

Follow the JavaScript convention of stacking `else/catch` clauses on the same line as the previous closing brace.

*Right:*

```TypeScript
if (i % 2 === 0) {
    console.log("even");
} else {
    console.log("odd");
}
```

*Wrong:*

```TypeScript
if (i % 2 === 0) {
    console.log("even");
}
else {
    console.log("odd");
}
```

## Variable declarations

Declare variables with `let` instead of `var`. Use `const` when possible.

*Right:*

```TypeScript
const button = new Button();

for (let i = 0; i < items.length; i++) {
    // do something
}
```

*Wrong:*

```TypeScript
var button = new Button();

for (var i = 0; i < items.length; i++) {
    // do something
}

```

## Variable and property names

Variables and properties should use [lower camel case][camelcase]
capitalization. They should also be descriptive. Single character variables and
uncommon abbreviations should generally be avoided unless it is something well known as **i** in for loops

*Right:*

```TypeScript
let adminUser = db.query("SELECT * FROM users ...");
```

*Wrong:*

```TypeScript
let admin_user = db.query("SELECT * FROM users ...");
```

[camelcase]: https://en.wikipedia.org/wiki/camelCase#Variations_and_synonyms

## Type names

Type names should be capitalized using [upper camel case][camelcase].

*Right:*

```TypeScript
class UserAccount() {
  this.field = "a";
}
```

*Wrong:*

```TypeScript
class userAccount() {
  this.field = "a";
}
```

## Constants

Constants should be declared with CAPITAL letters and `const` keyword. Use underscore to name constants with complex wording.

*Right:*

```TypeScript
const SECOND = 1 * 1000;
const MY_SECOND = SECOND;
```

*Wrong:*

```TypeScript
var second = 1 * 1000;
```

## Object / Array creation

Use trailing commas and put *short* declarations on a single line. Only quote
keys when your interpreter complains:

*Right:*

```TypeScript
let a = ["hello", "world"];
let b = {
  good: "code",
  "is generally": "pretty",
};
```

*Wrong:*

```TypeScript
let a = [
  "hello", "world"
];
let b = {"good": "code"
        , is generally: "pretty"
        };
```

## Equality operator

Use the [strict comparison operators][comparisonoperators]. The triple equality operator helps to maintain data type integrity throughout code.

*Right:*

```TypeScript
let a = 0;
if (a === "") {
    console.log("winning");
}

```

*Wrong:*

```TypeScript
let a = 0;
if (a == "") {
    console.log("losing");
}
```

[comparisonoperators]: https://developer.mozilla.org/en/JavaScript/Reference/Operators/Comparison_Operators

## Short-hand operators

Try to avoid short-hand operators except in very simple scenarios.

*Right:*

```TypeScript
let default = x || 50;
let extraLarge = "xxl";
let small = "s"
let big = (x > 10) ? extraLarge : small;
```

*Wrong:*

```TypeScript
let default = checkX(x) || getDefaultSize();
let big = (x > 10) ? checkX(x) ? getExtraLarge() : getDefaultSize() : getSmallValue();
```

## Curly braces 

Always use curly braces even in the cases of one line conditional operations.

*Right:*

```TypeScript
if (a) {
    return "winning";
}

```

*Wrong:*

```TypeScript

if (a)
    return "winning";

if (a) return "winning";
```

## Boolean comparisons

**Do not** directly compare with `true` or `false`.

*Right:*

```TypeScript

if(condition) {
    console.log("winning");
}

if (!condition) {
    console.log("winning");
}

```

*Wrong:*

```TypeScript

if(condition === true) {
    console.log("losing");
}

if(condition !== true) {
    console.log("losing");
}

if(condition !== false) {
    console.log("losing");
}

```

## Boolean conditions format
Do not use the **Yoda Conditions** when writing boolean expressions:

*Right:*

```TypeScript
let num;
if(num >= 0) {
    console.log("winning");
}
```

*Wrong:*

```TypeScript
let num;
if(0  {
    exp1();
    exp2();
    this.doSomething();
});
```

*Wrong:*

```TypeScript
let that = this;
req.on("end", function () {
    exp1();
    exp2();
    that.doSomething();
});
```

## Comments

Use the [JSDoc][JSDOC] convention for comments. When writing a comment always think how understandable will be for somebody who is new to this code. Even if it may look simple to you think how a guy that just joined will understand it. Always comment in the following cases:
+ When there is some non-trivial logic.
+ Some "external" knowledge is needed which is missing in the context - workaround for driver, module bug, special 'hack' because of a bug and so on;
+ When you are creating a new class
+ Public methods - include all the arguments and if possible the types {String}, {Number}. Optional arguments should be marked too. Check the [@param tag][param]

[JSDOC]: http://usejsdoc.org/
[param]: http://usejsdoc.org/tags-param.html

## File/module structure

Typical module should have the following structure:

1. required dependencies
2. module-private declarations - variables, functions, classes, etc.
3. export variables and functions
4. export class declarations

For more information see [this file](https://github.com/telerik/xPlatCore/blob/master/JS/BCL/CreateNewModule.md)

## File naming
Use lower case for file names. Use dash to separate different words.

*Right:*
file-system

*Wrong:*
FileSystem, fileSystem, file_system

## This, that, self
When you **need** to keep reference to **this** use **that** as the name of the variable. Additionally, if you use the TypeScript lambda support, the compiler will take care of this automatically.

*Right:*
```TypeScript
let that = this;
doSomething(function(){
    that.doNothing();
});
```

*Wrong:*
```TypeScript
let me = this;
doSomething(function(){
    me.doNothing();
});
```

## Private (hidden) variables and methods
Although there is the **private** keyword in TypeScript, it is only a syntax sugar. There is no such notation in JavaScript and everything is available to the users. Hence, always use underscore (**_**) to prefix private variables and methods. There are also methods which have the **public** visibility but they are meant to be used within our code ONLY. Such methods should also be prefixed with underscore.

*Right:*
```TypeScript
class Foo {
    private _myBoolean: boolean;
    
    public publicAPIMethod() {
    }
    
    public _frameworkMethod() {
        // this method is for internal use only
    }
    
    private _doSomething() {
    }
}
```

*Wrong:*
```TypeScript
class Foo {
    private myBoolean: boolean;
    
    public _publicAPIMethod() {
    }
    
    public frameworkMethod() {
        // this method is for internal use only
    }
    
    private doSomething() {
    }
}
```

## TypeScript optional parameters
**Do not** use optional parameters in IMPLEMENTATION files. This is because the TS compiler generates additional array and populates its from the **arguments** object. Still, it is OK to use these in a definition file (as declarations ONLY).

*Right:*
```TypeScript
// declaration
export declare function concat(...categories: string[]): string;

// implementation
export function concat(): string {
    let i;
    let result: string;
    // use the arguments object to iterate the parameters
    for (i = 0; i < arguments.length; i++) {
        // do something
    }

    return result;
}
```

*Wrong:*
```TypeScript
// declaration
export declare function concat(...categories: string[]): string;

// implementation
export function concat(...categories: string[]): string {
    let i;
    let result: string;
    // use the arguments object to iterate the parameters
    for (i = 0; i < categories.length; i++) {
        // do something
    }

    return result;
}
```

## Naming test functions
Name your test function with `test_` so that our test runner can find them and add 'underscore' tested method/property name. Different words should be capitalized (and optionally separated by 'underscore').

*Right:*
```TypeScript
export function test_goToVisualState_NoState_ShouldResetStyledProperties() {
    // Test code here.
}
```