Changes between Version 12 and Version 13 of CodingStyle


Ignore:
Timestamp:
Feb 13, 2014, 12:52:12 PM (6 years ago)
Author:
Piotrek Koszuliński
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CodingStyle

    v12 v13  
    1 [[TOC]]
    2 
    31= Coding Style Guidelines =
    42
    5 Those guidelines where defined based on mixed common standards mainly related to Java and C# programming.
    6 
    7 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.
    8 
    9 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.
    10 
    11 The following definitions are based on long years of experience with pure !JavaScript coding.
    12 
    13 == General Recommendations ==
    14 
    15 Any violation to the guide is allowed if it enhances readability.
    16 
    17 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.
    18 
    19 The name "!JavaScript" should be written with both the "J" and "S" in uppercase. The following are wrong: "Javascript", "javascript", etc.
    20 
    21 == Naming Conventions ==
    22 
    23 === Generic Name Conventions ===
    24 
    25 Names representing packages must be in PascalCase. Whenever applicable, the package name will be prefixed with "FCKeditor.".
    26 
    27 {{{
    28     FCKeditor, FCKeditor.Net, FCKeditor.Java
    29 }}}
    30 
    31 Names representing public classes and public global objects must be in PascalCase and prefixed with "FCK".
    32 
    33 {{{
    34     FCKBrowserInfo, FCKToolbarButton
    35 }}}
    36 
    37 Names representing constants must be all uppercase.
    38 
    39 {{{
    40     FCK_STATUS_COMPLETE, FCK_EDITMODE_WYSIWYG, CTRL
    41 }}}
    42 
    43 Names representing public methods must be verbs and written in PascalCase.
    44 
    45 {{{
    46     AppendStyleSheet(), GetElementDocument(), SetTimeout()
    47 }}}
    48 
    49 Names representing public properties must be nouns and written in PascalCase.
    50 
    51 {{{
    52     Name, Document, TargetWindow
    53 }}}
    54 
    55 Names representing private methods must be verbs and written in PascalCase prefixed with an underscore.
    56 
    57 {{{
    58     _DoInternalStuff()
    59 }}}
    60 
    61 Names representing private properties must be nouns and written in PascalCase prefixed with an underscore.
    62 
    63 {{{
    64     _InternalCounter, _Prefix
    65 }}}
    66 
    67 Names representing private global function must be in PascalCase prefixed with an underscore.
    68 
    69 {{{
    70     function _DoSomething()
    71 }}}
    72 
    73 Abbreviations and acronyms should not be uppercase when used as name.
    74 
    75 {{{
    76     SetHtml(), XmlDocument
    77     NOT
    78     SetHTML(), XMLDocument
    79 }}}
    80 
    81 All names should be written in English.
    82 
    83 === Specific Name Conventions ===
    84 
    85 The prefixes "Get" and "Set" may be used on methods that get or set properties which require computation.
    86 
    87 {{{
    88     SetArrayCount(), GetFormattedValue()
    89 }}}
    90 
    91 The prefix "!CheckIs" may be used on methods which return boolean states which require computation.
    92 
    93 {{{
    94     CheckIsValid(), CheckIsEmpty()
    95 }}}
    96 
    97 Abbreviations in names should be avoided.
    98 
    99 {{{
    100     GetDirectoryName(), applicationCommand
    101     NOT
    102     GetDirName(), appCmd
    103 }}}
    104 
    105 == Files ==
    106 
    107 All files must be named in all lower case.
    108 
    109 Classes and global objects should be declared in individual files with the file name matching the class/object name.
    110 
    111 {{{
    112     fckbrowserinfo.js, fcktoolbarbutton.js
    113 }}}
    114 
    115 == Layout ==
    116 
    117 For indentation, the TAB should be used. Development IDEs should be configured to represent TABs as 4 spaces.
    118 
    119 {{{
    120     if ( test )
    121     {
    122         if ( otherTest )
    123             DoSomething() ;
    124         DoMore() ;
    125     }
    126 }}}
    127 
    128 Block layout should be as illustrated.
    129 
    130 {{{
    131     while ( !done )
    132     {
    133         DoSomething() ;
    134         done = MoreToDo() ;
    135     }
    136 }}}
    137 
    138 Single statement if/else/while/for could (preferably) be written without brackets, but never in the same line.
    139 
    140 {{{
    141     if ( condition )
    142         statement ;
    143 
    144     while ( condition )
    145         statement ;
    146 
    147     for ( initialization ; condition ; update )
    148         statement ;
    149 }}}
    150 
    151 The incompleteness of split lines must be made obvious.
    152 
    153 {{{
    154     totalSum = a + b + c +
    155         d + e ;
    156 
    157     Method( param1, param2,
    158         param3 ) ;
    159 
    160     SetText( 'Long line split' +
    161         'into two parts.' ) ;
    162 
    163 }}}
    164 
    165 === Whitespace ===
    166 
    167 Conventional operators should be surrounded by a space (including ternary operators).
    168 
    169 {{{
    170     if ( i > 3 && test == 'yes' )
    171 }}}
    172 
    173 Commas should be followed by a space.
    174 
    175 {{{
    176     function MyFunction( parm1, param2, param3 )
    177 }}}
    178 
    179 Semi-colons in for statements should be surrounded by a space.
    180 {{{
    181     for ( var i = 0 ; i < count ; i++ )
    182 }}}
    183 
    184 Semi-colons should be preceded by a space.
    185 {{{
    186     DoSomething() ;
    187     var name = 'John' ;
    188 }}}
    189 
    190 Colons should be surrounded by a space.
    191 {{{
    192     case 100 :
    193     NOT
    194     case 100:
    195 }}}
    196 
    197 Opening parenthesis must be followed by a space and closing parenthesis must be preceded by a space.
    198 
    199 {{{
    200    if ( myVar == 1 )
    201 }}}
    202 
    203 Functions/method calls should not be followed by a space.
    204 
    205 {{{
    206     DoSomething( someParameter ) ;
    207     NOT
    208     doSomething ( someParameter ) ;
    209 }}}
    210 
    211 Logical units within a block should be separated by one blank line.
    212 
    213 {{{
    214     // Create a new identity matrix
    215     var matrix = new Matrix4x4() ;
    216 
    217     // Precompute angles for efficiency
    218     var cosAngle = MathCos( angle ) ;
    219     var sinAngle = MathSin( angle ) ;
    220 
    221     // Specify matrix as a rotation transformation
    222     matrix.SetElement( 1, 1, cosAngle ) ;
    223     matrix.SetElement( 1, 2, sinAngle ) ;
    224     matrix.SetElement( 2, 1, -sinAngle ) ;
    225     matrix.SetElement( 2, 2, cosAngle ) ;
    226 
    227     // Apply rotation
    228     transformation.Multiply( matrix ) ;
    229 }}}
    230 
    231 == Variables ==
    232 
    233 Variables must be always defined with "var".
    234 
    235 Function parameters must be in camelCase.
    236 
    237 {{{
    238     function Sum( firstNumber, secondNumber )
    239 }}}
    240 
    241 Local variables must be in camelCase.
    242 
    243 {{{
    244     function DoSomething()
    245     {
    246         var colorOne = 1 ;
    247         var colorTwo = 2 ;
    248 
    249         return colorOne + colorTwo ;
    250     }
    251 }}}
    252 
    253 == Comments ==
    254 
    255 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.
    256 
    257 All comments should be written in English. Whenever possible, end comments with a period as normal phrases, and wrap comments within the first 80 characters of each line.
    258 
    259 There should be a space after the comment identifier.
    260 
    261 {{{
    262     // This is a comment.    NOT: //This is a comment
    263     /**                      NOT: /**
    264      * This is block               *This is a block
    265      * comment.                    *comment
    266      */                            */
    267 }}}
    268 
    269 == Regular Expressions ==
    270 
    271 The '''regular expression literal''' should be used whenever possible, instead of the RegExp object, which should be used only when the regular expression pattern is not constant or depends on runtime computation.
    272 
    273 {{{
    274     /^foo\s*/i
    275     NOT
    276     new RegExp( '^foo\s*', 'i' )
    277 }}}
    278 
    279 Other than shortnesses and better readability, regular expression literals are compiled during script evaluation, which improves performance.
    280 
    281 == File Headers ==
    282 
    283 There are minimum requirements for us to be able to make our code available to the world. Most of them are related to legal needs, which help us protecting the project from abuses.
    284 
    285 Here is a JavaScript template for the header to be included in the source code:
    286 
    287 {{{
    288 /*
    289  * FCKeditor - The text editor for Internet - http://www.fckeditor.net
    290  * Copyright (C) 2003-2008 Frederico Caldeira Knabben
    291  *
    292  * == BEGIN LICENSE ==
    293  *
    294  * Licensed under the terms of any of the following licenses at your
    295  * choice:
    296  *
    297  *  - GNU General Public License Version 2 or later (the "GPL")
    298  *    http://www.gnu.org/licenses/gpl.html
    299  *
    300  *  - GNU Lesser General Public License Version 2.1 or later (the "LGPL")
    301  *    http://www.gnu.org/licenses/lgpl.html
    302  *
    303  *  - Mozilla Public License Version 1.1 or later (the "MPL")
    304  *    http://www.mozilla.org/MPL/MPL-1.1.html
    305  *
    306  * == END LICENSE ==
    307  *
    308  * [File Description]
    309  */
    310 }}}
    311 
    312 Of course, different languages have different commenting syntax, so it is enough to copy the header from an existing file to maintain the style.
    313 
    314 === Author Tags ===
    315 
    316 Author names, e-mails or web site addresses should be avoided in the header. To justify that, let me recall a citation from Sander Striker, a member of the Apache Software Foundation, that can be found at [http://producingoss.com/en/managing-volunteers.html#territoriality Producing Open Source Software]:
    317 
    318     At the Apache Software foundation we discourage the use of author tags in source code. There are various reasons for this, apart from the legal ramifications. Collaborative development is about working on projects as a group and caring for the project as a group. Giving credit is good, and should be done, but in a way that does not allow for false attribution, even by implication. There is no clear line for when to add or remove an author tag. Do you add your name when you change a comment? When you put in a one-line fix? Do you remove other author tags when you refactor the code and it looks 95% different? What do you do about people who go about touching every file, changing just enough to make the virtual author tag quota, so that their name will be everywhere?
    319 
    320     There are better ways to give credit, and our preference is to use those. From a technical standpoint author tags are unnecessary; if you wish to find out who wrote a particular piece of code, the version control system can be consulted to figure that out. Author tags also tend to get out of date. Do you really wish to be contacted in private about a piece of code you wrote five years ago and were glad to have forgotten?
    321 
    322 The SVN is a good place to understand user participation. Even when committing changes proposed by Joe White, it is nice to add a comment like "Thanks to Joe White." in the commit message.
     3**See [https://github.com/ckeditor/ckeditor-idiomatic.js Code Style guide].**
© 2003 – 2019 CKSource – Frederico Knabben. All rights reserved. | Terms of use | Privacy policy