JavaScript Authoring style Guide (ii)

Seven: Notes

Frequent use of annotations helps others to understand your code
1. The code is obscure and difficult to understand
2. Code that may be mistaken for error
3. Necessary, but not obvious, browser-specific code
4. For objects, methods or properties, it is necessary to generate documents (using appropriate documentation comments)

Seven (a): single-line comment

A single-line comment should be used to describe a line of code or a set of related code. There may be three ways to use a single line of comments
1. An exclusive line of comments that explains the code for the next line
2. A comment at the end of the line of code that is used to interpret it before the code
3. Multiple lines, used to comment out a block of code

Example:

Good wording.
if (condition) {

If the code executes here, it means that all security checks are passed
Allowed ();
}

Bad notation: No blank lines before comments
if () {
If the code executes here, it means that all security checks are passed
Allowed ();


Bad notation: the wrong indentation
if () {

If the code executes here, it means that all security checks are passed
Allowed ();
}

Good wording.
var result = something + somethingelse; Comments

Bad notation: There are no spaces between the code and the comment
var result = something + somethingelse;//comment

When commenting on a block of code, it is only acceptable to use a single-line comment in consecutive lines
Multi-line annotations should not be used in this case

Good wording.
if (condition) {
DoSomething ();
Thedosomethingelse ();
// }


Seven (b): Multiline comment

Multi-line annotations should be used when the code needs more text to explain, with at least three lines for each multiline comment.
1. The first line only includes the/* Comment start. The line should not have other text
2. The next line * begins and remains aligned to the left. These lines can be described with text
3. The last line starts with */and remains aligned with the previous one. And there should be no other words

The first line of a multiline comment retains the same level of indentation as it describes the code, and each subsequent line should have the same
Indent the hierarchy and append a space. One blank line should be reserved before each multiline line of code

Good wording.
if (condition) {

/*
* If the code executes here
* Indicates that all security checks have been passed
*/
Allowed ();
}

Bad wording: No blank line before comment
if (condition) {
/*
* If the code executes here
* Indicates that all security checks have been passed
*/
Allowed ();
}

Seven (c): Multi-line Declaration

Annotations can also sometimes be used to declare additional information for a piece of code. These declarations are formatted with a single word
Begin with a colon. The following statements can be used:

TODO: The description code is not complete and should contain the next thing to do
HACK: Shows the code implementation took a shortcut. Should include reasons why the use of hack.
This may also indicate that there may be a better way to resolve the problem
XXX: Description code is problematic and should be repaired as soon as possible
Fixme: The description code is problematic and should be repaired as soon as possible. Importance slightly times with XXX
REVIEW: Description Code any possible changes are subject to review

These declarations may be used in one or more lines of comments and should follow the same formatting rules as the same annotation type

Example:

Good wording.
TODO: I want to find a way to always be faster
DoSomething ();

Good wording.
/*
* HACK: Have to do special treatment for IE. I plan to have time to follow.
* Rewrite this section. This code may need to be replaced before the 1.72 release.
*/
if (document.all) {
DoSomething ();
}

Seven (four): Multi-line Declaration

All variables should be defined beforehand before they are used. The variable definition should be placed at the beginning of the function, and there is a Var
expression, one variable per line, except for the first line. All rows should be indented so that the variable name can be vertically
aligned in the direction. The variable definition should be initialized, and the assignment operator maintains a consistent indentation. Initialization
Variables should be preceded by uninitialized variables

Good wording.
var count = 10,
Name = "M",
Found = False,
Empty

Bad notation: the wrong indentation
var count= 10,
Name = "M",
Found = False,
Empty

Bad notation: Uninitialized variables are placed in the front
var empty,
Count = 10,
Name = "M",
Found = False,

Seven (v): function declaration

The function should be defined in advance before use. A function that is not a method (that is, not as a
The format of the function definition (not the function expression and the functions constructor format) should be used
There should be no spaces between the function name and the opening parenthesis. Close the parentheses and the right curly braces should be noted between
a space. The curly brace on the right should remain on the same line as the function keyword. Between opening and closing parentheses should not be
There should be a space. You should leave a space after the comma between the parameters. The function body should be indented at one level.

Good wording.
function dosomething (arg1, arg2) {
return arg1 + arg2;
}

Bad wording: The first line of inappropriate spaces
function dosomething (arg1, arg2) {
return arg1 + arg2;
}

Bad notation: function expressions
var dosomething = function (Arg1, arg2) {
return arg1 + arg2;
}

Functions defined internally by other functions should be defined immediately after the VAR statement

Good wording.
function outer () {
var count = 10,
Name = "M",
Found = False,
Empty

function inner () {
Code
}
}

Bad wording.
function outer () {

function inner () {
Code
}

var count = 10,
Name = "M",
Found = False,
Empty
}

An anonymous function may be assigned to an object as a method, or as an argument to another function. function keyword
There should be no spaces between the same opening brackets

Good wording.
Object.Method = function () {
Code
};

Bad wording.
Object.Method = function () {
Code
};

Functions that are called immediately should be wrapped in parentheses in the outer layer of the function call
Good wording.
var value = (function () {

function body

return {
Message: "Hi"
}
}());

Bad notation: Parentheses are not positioned properly
var value = (function () {

function body

return {
Message: "Hi"
}
})();

Seven (vi): Naming

Variables and functions should be named with caution. Naming should only be restricted with an array of alphabetic characters, and in some cases can also be used
Underline. It is best not to use a dollar sign ($) or a backslash (\) in any naming.

The name of the variable should also be in the Hump naming format, with the first letter lowercase and each word capitalized. The name of the variable
A word should be a noun (not a verb) to avoid confusion with the function. Do not use underscores in variable naming

Good wording.
var accountnumber = "23454";

Bad notation: capital letters start with
var accountnumber = "23454";

Bad writing: The beginning of a verb
var getaccountnumber = "23454";

Bad writing: using the glide line
var account_number = "23454";

The name of the function should also be used in the Camel name format. The first word of a function name should be a verb (not a noun)
To avoid confusion with the same variables. It is best not to use underscores in function names

Good wording.
function dosomething () {
Code
}

Bad notation: capital letters start with
function dosomething () {
Code
}

Bad wording: using underscores
function do_something () {
Code
}

The constructor---The function that creates the new object through the newly operator---should also be named in the hump format, and
Capitalized, the constructor name should begin with a non-verb because new represents an action to create an object instance

Good wording.
function MyObject () {
Code
}

Bad syntax: Start with a lowercase letter
function MyObject () {
Code
}

Bad wording: using underscores
function My_object () {
Code
}

Bad writing: start with a verb
function Getmyobject () {
Code
}

Constants (variables that do not change values) should be named for all uppercase letters, separated by a single slide between different words

Good wording.
var total_count = 10;

An object's properties are the same as a variable's naming convention. The method of the object is the same as the naming convention for the function. If the property
Or the method is private, it should be preceded by an underscore

Good wording.
var object = {
_count:10,

_getcount:function () {
return this._count;
}
};

JavaScript Authoring style Guide (ii)