Changes between Initial Version and Version 1 of CodingStyle

Timestamp:

Dec 4, 2006, 12:50:08 PM (18 years ago)

Author:

Frederico Caldeira Knabben

Comment:

--

CodingStyle

@@ +1 @@
+= Coding Style Guidelines =
+
+Those guidelines where defined based on mixed common standards mainly related to Java and C# programming. 
+
+It is quite common to take the Java style to write !JavaScript code, assuming it is a "cut-down" version of Java. Although !JavaScript has an indirect relation with Java, apart from the similar "C style" syntax, it has nothing to do with it. It is not a class based language. It is an interpreted, object based, loosely typed scripting language. It can run only in the presence of a "host" application, like a web browser.
+
+If we instead take a closer look at C# code standards (from Microsoft), we'll not more modern and readable proposals, which help also on identifying custom code from the underlying host environment.
+
+The following definitions are based on long years of experience with pure !JavaScript coding.
+
+== General Recommendations ==
+
+Any violation to the guide is allowed if it enhances readability.
+
+The name "FCKeditor" is used, it must always be written with "FCK" uppercased concatened with "editor" in lowercase. The following are wrong: "!FckEditor", "FCKEditor", "fckEditor", "FCK Editor", and so on. Exception is made for directory names, where all chars "should" be in lowercase.
+
+The name "!JavaScript" should be written with both the "J" and "S" in uppercase. The following are wrong: "Javascript", "javascript", etc.
+
+== Naming Conventions ==
+
+=== Generic Name Conventions ===
+
+Names representing packages must be in CamelCase. Whenever applicable, the package name will be prefixed with "FCKeditor.".
+
+{{{
+    FCKeditor, FCKeditor.Net, FCKeditor.Java
+}}}
+
+Names representing public classes and public global objects must be in CamelCase and prefixed with "FCK".
+
+{{{
+    FCKBrowserInfo, FCKToolbarButton
+}}}
+
+Names representing constants must be all uppercase.
+
+{{{
+    FCK_STATUS_COMPLETE, FCK_EDITMODE_WYSIWYG, CTRL
+}}}
+
+Names representing public methods must be verbs and written in CamelCase.
+
+{{{
+    AppendStyleSheet(), GetElementDocument(), SetTimeout()
+}}}
+
+Names representing public properties must be verbs and written in CamelCase.
+
+{{{
+    Name, Document, TargetWindow
+}}}
+
+Names representing private methods must be verbs and written in CamelCase prefixed with an underscore.
+
+{{{
+    _DoInternalStuff()
+}}}
+
+Names representing private properties must be verbs and written in CamelCase prefixed with an underscore.
+
+{{{
+    _InternalCounter, _Prefix
+}}}
+
+Names representing private global function must be in CamelCase prefixed with an underscore.
+
+(((
+    function _DoSomething()
+)))
+
+Abbreviations and acronyms should not be uppercase when used as name.
+
+{{{
+    SetHtml(), XmlDocument
+    NOT
+    SetHTML(), XMLDocument
+}}}
+
+All names should be written in English.
+
+=== Specific Name Conventions ===
+
+The prefixes "Get" and "Set" may be used on methods that get or set properties which require computation.
+
+{{{
+    SetArrayCount(), GetFormattedValue()
+}}}
+
+The prefix "!CheckIs" may be used on methods which return boolean states which require computation.
+
+{{{
+    CheckIsValid(), CheckIsEmpty()
+}}}
+
+Abbreviations in names should be avoided.
+
+{{{
+    GetDirectoryName(), applicationCommand
+    NOT
+    GetDirName(), appCmd
+}}}
+
+== Files ==
+
+All files must be named in all lower case.
+
+Classes and global objects should be declared in individual files with the file name matching the class/object name.
+
+{{{
+    fckbrowserinfo.js, fcktoolbarbutton.js
+}}}
+
+== Layout ==
+
+For indentation, the TAB should be used. Development IDEs should be configured to represent TABs as 4 spaces.
+
+{{{
+    if ( test )
+    {
+        if ( otherTest )
+            DoSomething() ;
+        DoMore() ;
+    }
+}}}
+
+Block layout should be as illustrated.
+
+{{{
+    while ( !done )
+    {
+        doSomething() ;
+        done = moreToDo() ;
+    }
+}}}
+
+Single statement if/else/while/for should be written without brackets, but never in the same line.
+
+{{{
+    if ( condition )
+        statement ;
+
+    while ( condition )
+        statement ;
+
+    for ( initialization ; condition ; update )
+        statement ;
+}}}
+
+The incompleteness of split lines must be made obvious.
+
+{{{
+    totalSum = a + b + c + 
+        d + e ; 
+
+    method( param1, param2,
+        param3 ) ; 
+
+    setText( 'Long line split' + 
+        'into two parts.' ) ;
+
+}}}
+
+=== Whitespace ===
+
+Conventional operators should be surrounded by a space (including ternary operators).
+
+{{{
+    if ( i > 3 && test == 'yes' )
+}}}
+
+Commas should be followed by a space.
+
+{{{
+    function MyFunction( parm1, param2, param3 )
+}}}
+
+Semi-colons in for statements should be surrounded by a space.
+{{{
+    for ( var i = 0 ; i < count ; i++ )
+}}}
+
+Semi-colons should be preceded by a space.
+{{{
+    DoSomething() ;
+    var name = 'John' ;
+}}}
+
+Colons should be surrounded by a space.
+{{{
+    case 100 :
+    NOT
+    case 100:
+}}}
+
+Opening parenthesis must be followed by a space and closing parenthesis must be preceded by a space.
+
+{{{
+   if ( myVar == 1 )
+}}}
+
+Functions/method calls should not be followed by a space.
+
+{{{
+    DoSomething( someParameter ) ;
+    NOT
+    doSomething ( someParameter ) ;
+}}}
+
+Logical units within a block should be separated by one blank line.
+
+{{{
+    // Create a new identity matrix
+    var matrix = new Matrix4x4() ;
+
+    // Precompute angles for efficiency 
+    var cosAngle = MathCos(angle) ;
+    var sinAngle = MathSin(angle) ;
+
+    // Specify matrix as a rotation transformation 
+    matrix.SetElement( 1, 1, cosAngle ) ;
+    matrix.setElement( 1, 2, sinAngle ) ; 
+    matrix.setElement( 2, 1, -sinAngle ) ;
+    matrix.setElement( 2, 2, cosAngle ) ;
+
+    // Apply rotation
+    transformation.multiply( matrix ) ;
+}}}
+
+== Variables ==
+
+Variables must be always defined with "var".
+
+Function parameters must be in pascalCase.
+
+{{{
+    function Sum( firstNumber, secondNumber )
+}}}
+
+Local variables must be in pascalCase. 
+
+{{{
+    function DoSomething()
+    {
+        var colorOne = 1 ;
+        var colorTwo = 2 ;
+
+        return colorOne + colorTwo ;
+    }
+}}}
+
+== Comments ==
+
+Tricky code should not be commented but rewritten: In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure.
+
+All comments should be written in English.
+
+There should be a space after the comment identifier.
+
+{{{
+    // This is a comment     NOT: //This is a comment 
+    /**                      NOT: /** 
+     * This is block               *This is a block 
+     * comment                     *comment 
+     */                            */
+}}}
+
+----