Skip to content
This repository has been archived by the owner on Aug 24, 2021. It is now read-only.

Add Javascript Coding Standard #91 #111

Closed
wants to merge 3 commits into from
Closed

Add Javascript Coding Standard #91 #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bd05c0f
Fixes #91
sihaoo Dec 22, 2015
fb28c36
1. Updated format to adhere to example #97
sihaoo Jan 4, 2016
1448e85
Made changes according to comments
sihaoo Jan 5, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ If you would like to contribute code, here is the procedure:
* Minimize inline styles.
* When in doubt, you can refer to these style guides from the
TEAMMATES project:
[JavaScript](https://docs.google.com/document/d/1gZ6WG6HBTJYHAtVkz9kzi_SUuzfXqzO-SvFnLuag2xM/pub?embedded=true),
[JavaScript](https://cdn.rawgit.com/nus-cs2103/website/master/contents/coding-standards-javascript.html),
[CSS](https://docs.google.com/document/d/1wA9paRA9cS7ByStGbhRRUZLEzEzimrNQjIDPVqy1ScI/pub),
[HTML](https://docs.google.com/document/d/12PJYbQoqjK-0LzaUuguQ4kGE--eikCcHfwzZDGwFOJ0/pub?embedded=true)
6. Test the code in your computer. <br>
Expand Down
26 changes: 26 additions & 0 deletions contents/coding-standards-javascript.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!DOCTYPE html>
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
<link href="https://assets-cdn.github.com/assets/github-502ab50993b65c1ac75efa286ffd5304245f6c9bb4171ac014fbcf92f6f688de.css" rel="stylesheet">
<link href="https://assets-cdn.github.com/assets/github2-36c3357696d7a0b54cfebf9eae59bf8e7739f834491862e897feaa0f6118eddc.css" rel="stylesheet">
<link href="../styles/markdown.css" rel="stylesheet">
<title>Javascript Style Guide</title>
</head>
<body>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script>
var markdownUrl = 'coding-standards-javascript.md';

function processAndDisplayResult(html) {
// pre-process the result as necessary

// display the result in the page; this is the minimum requirement of the function
displayResult(html);

// post-process the result as necessary
}
</script>
<script src="../scripts/markdown.js"></script>
</body>
</html>
273 changes: 273 additions & 0 deletions contents/coding-standards-javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,273 @@
# Javascript Style Guide

- <a href="#specific-rules">Specific Rules</a>
- <a href="#general-rules">General Rules</a>
- <a href="#additional-reading">Additional Reading</a>

## Specific Rules
- __Line Break Limit__

Limits are at 110 characters instead of 80 characters

- __Indentation__

Indentation should be 4 spaces for javascript files.
4 spaces should be used instead of 2 spaces or `tab`.

- __Constants__

Constant should use screaming snake case

<table>
<tr>
<th align="center">Good</th>
<th align="center">Bad</th>
</tr>
<tr>
<td>
<pre lang="javascript">
// G_O_O_D
var FOO_BAR_DESCRIPTION = 'helloworld';
</pre>
</td>
<td>
<pre lang="javascript">
// bad
var foobardescription = 'helloworld';
</pre>
</td>
</tr>
<tr>
<td>
</td>
<td>
<pre lang="javascript">
// badAsWell
var fooBarDescription = 'helloworld';
</pre>
</td>
</tr>
<tr>
<td>
</td>
<td>
<pre lang="javascript">
// b_a_d
var foo_bar_description = 'helloworld';
</pre>
</td>
</tr>
<tr>
<td>
</td>
<td>
<pre lang="javascript">
// bad
var foobardescription = 'helloworld';
</pre>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is duplication of the first bad example.

</td>
</tr>
</table>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, for this table, rather than making the good and the bad side-by-side (not balanced since there are 3 bad examples), you can make the table entirely sequential, for e.g the example of good/bad attributes in the HTML coding standard.


- __Line wrapping rules__

Line wrapping rules for improving readability <a href="https://cdn.rawgit.com/nus-cs2103/website/master/contents/coding-standards-java.html">[follow Java Style Guide files rule 3]</a>

When wrapping lines, the main objective is to improve readability. Feel free to break rules if it improves readability.
It is OK to exceed the limit slightly or wrap the lines much shorter than limit.

In general,
- Break after a comma.

<table>
<tr>
<th align="center">Good</th>
<th align="center">Bad</th>
</tr>
<tr>
<td>
<pre lang="javascript">
// Good
var alphabets = [
a,
b,
c
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indent 4 spaces as mentioned in this guide.

];
</pre>
</td>
<td>
<pre lang="javascript">
// Bad
var alphabets = [
a
, b
, c
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here too. The issue here is misplaced comma, not bad indentation.

];
</pre>
</td>
</tr>
<tr>
<td>
<pre lang="javascript">
// Good
var numbers = {
one: 1,
two: 2,
three: 3,
four: 4
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here as well.

};
</pre>
</td>
<td>
<pre lang="javascript">
// Bad
var numbers = {
one: 1
, two: 2
, three: 3
, four: 4
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And here.

};
</pre>
</td>
</tr>
</table>

- Align the new line with the beginning of the parent element.

<table>
<tr>
<th align="center">Good</th>
<th align="center">Bad</th>
</tr>
<tr>
<td>
<pre lang="javascript">
// Good
myFunction(arg1, arg2
arg3, arg4);
myFunction(arg1,
myOtherFunction(arg2,
arg3),
arg4);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The alignment is wrong here. What is intended:

myFunction(arg1, arg2
           arg3, arg4);
myFunction(arg1,
           myOtherFunction(arg2,
                           arg3),
           arg4);

</pre>
</td>
<td>
<pre lang="javascript">
// Bad
myFunction(arg1, arg2, arg3,
nonAlignedArg4, arg5);
</pre>
</td>
</tr>
</table>

- Break before an operator. This also applies to other "operator-like" symbols like the dot separator (.).

<table>
<tr>
<th align="center">Good</th>
<th align="center">Bad</th>
</tr>
<tr>
<td>
<pre lang="javascript">
// Good
mySum = a b c
d;
myString = 'Long line split'
'split into two parts';
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you somehow removed all the +s.

$('#responses')
.find('.selected')
.highlight()
.end()
.find('.open')
.updateCount();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From $('#responses') to .find('.selected') should be 4 spaces? Same for the bad example.

</pre>
</td>
<td>
<pre lang="javascript">
// Bad
mySum = a b c
d;
myString = 'Long line split'
'split into two parts';
$('#responses').
find('.selected').
highlight().
end().
find('.open').
updateCount();
</pre>
</td>
</tr>
</table>

- Prefer higher-level breaks to lower-level breaks. In the example below, the first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level.

<table>
<tr>
<th align="center">Good</th>
<th align="center">Bad</th>
</tr>
<tr>
<td>
<pre lang="javascript">
// Good
longName1 = longName2 * (longName3 longName4 - longName5)
4 * longName6;
</pre>
</td>
<td>
<pre lang="javascript">
// Bad
longName1 = longName2 * (longName3 longName4
- longName5) 4 * longName6;
</pre>
</td>
</tr>
</table>

- Here are three acceptable ways to format ternary expressions:

<table>
<tr>
<th align="center">Good</th>
<th align="center">Bad</th>
</tr>
<tr>
<td>
<pre lang="javascript">
// Good
alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression)
? beta
: gamma;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

alpha = (aLongBooleanExpression) ? beta
                                 : gamma;
alpha = (aLongBooleanExpression)
      ? beta
      : gamma;

</pre>
</td>
<td>
<pre lang="javascript">
// Bad
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression)
? beta
: gamma;
</pre>
</td>
</tr>
</table>

Main rule of the thumb: To be consistent with Java coding style

## General Rules
- Refer to [airbnb Javascript Style Guide](https://github.com/airbnb/javascript/tree/master/es5)

## Additional Reading
1. [Javascript Scoping and Hoisting](http://www.adequatelygood.com/JavaScript-Scoping-and-Hoisting.html)
2. [Truth Equality and Javascript](https://javascriptweblog.wordpress.com/2011/02/07/truth-equality-and-javascript/#more-2108)
3. [Future of Javascript (ES6 - Incoming Features)](https://github.com/lukehoban/es6features)
4. [ES6 Compatibility in Browsers](http://kangax.github.io/compat-table/es6/)