Difference between revisions of "JavaScript coding conventions"

From PKP Wiki
Jump to: navigation, search
(Changed visibility approach to reflect switch to Google approach)
(Recommend @constructor, @private and @protected because Eclipse understands them.)
Line 13: Line 13:
 
= Visibility =
 
= Visibility =
  
We do not generally use the @protected and @private markers that Google recommends. We do, however, implement the following nomenclature for class members (properties and methods):
+
We use the @constructor, @protected and @private markers that Google recommends and Eclipse understands.
* We group members by visibility and class (static) vs. object (instance) membership:
+
 
** private static class variables (start with underscore)
+
We group members by visibility and class (static) vs. object (instance) membership:
** private instance variabes (start with underscore)
+
* private static class variables (start with underscore)
** protected instance variables (discouraged)
+
* private instance variabes (start with underscore)
** public static class variables or instance variables are not allowed!
+
* protected instance variables (discouraged)
** public static methods
+
* public static class variables or instance variables are not allowed!
** public methods
+
* public static methods
** protected static methods
+
* public methods
** protected methods
+
* protected static methods
** private static methods (start with underscore)
+
* protected methods
** private methods (start with underscore)
+
* private static methods (start with underscore)
* Sections are divided with a three line // style comment indicating the class member category.
+
* private methods (start with underscore)
* An underscore at the start of the name marks a class member private. You are not supposed to use such a member outside scope even if the visibility is not enforced by closure.
+
 
* Protected class members are named like public methods but they must not be used outside of the inheritance hierarchy of the current class.
+
Sections are divided with a three line // style comment indicating the class member category.
 +
 
 +
An underscore at the start of the name marks a class member private. You are not supposed to use such a member outside scope even if the visibility is not enforced by closure.
 +
 
 +
Protected class members are named like public methods but they must not be used outside of the inheritance hierarchy of the current class.

Revision as of 09:04, 11 December 2010

Google Coding Conventions

We use Google's JavaScript style guide as a starting point for our own style guide.

Only deviations from the Google style guide will be documented here.

JsDoc Comments

We use JsDoc comments as outlined in the Google style guide with but we name the variable name directly after the @param tag and the type without curly braces.

Generally we encourage inline comments. These help readers of your code to understand the logic without having to understand every line of code. It's also a good practice to write inline comments before you write code so that you first think about the logic and semantics you want to implement and then about the syntax.

Visibility

We use the @constructor, @protected and @private markers that Google recommends and Eclipse understands.

We group members by visibility and class (static) vs. object (instance) membership:

  • private static class variables (start with underscore)
  • private instance variabes (start with underscore)
  • protected instance variables (discouraged)
  • public static class variables or instance variables are not allowed!
  • public static methods
  • public methods
  • protected static methods
  • protected methods
  • private static methods (start with underscore)
  • private methods (start with underscore)

Sections are divided with a three line // style comment indicating the class member category.

An underscore at the start of the name marks a class member private. You are not supposed to use such a member outside scope even if the visibility is not enforced by closure.

Protected class members are named like public methods but they must not be used outside of the inheritance hierarchy of the current class.