[Summary view] [Print] [Text view]

   1  @title Javascript Coding Standards
   2  @group standards
   3  
   4  This document describes Javascript coding standards for Phabricator and Javelin.
   5  
   6  = Overview =
   7  
   8  This document outlines technical and style guidelines which are followed in
   9  Phabricator and Javelin. Contributors should also follow these guidelines. Many
  10  of these guidelines are automatically enforced by lint.
  11  
  12  These guidelines are essentially identical to the Facebook guidelines, since I
  13  basically copy-pasted them. If you are already familiar with the Facebook
  14  guidelines, you can probably get away with skimming this document.
  15  
  16  
  17  = Spaces, Linebreaks and Indentation =
  18  
  19    - Use two spaces for indentation. Don't use literal tab characters.
  20    - Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
  21    - Use K&R style braces and spacing.
  22    - Put a space after control keywords like ##if## and ##for##.
  23    - Put a space after commas in argument lists.
  24    - Put space around operators like ##=##, ##<##, etc.
  25    - Don't put spaces after function names.
  26    - Parentheses should hug their contents.
  27    - Generally, prefer to wrap code at 80 columns.
  28  
  29  = Case and Capitalization =
  30  
  31  The Javascript language unambiguously dictates casing/naming rules; follow those
  32  rules.
  33  
  34    - Name variables using ##lowercase_with_underscores##.
  35    - Name classes using ##UpperCamelCase##.
  36    - Name methods and properties using ##lowerCamelCase##.
  37    - Name global functions using ##lowerCamelCase##. Avoid defining global
  38      functions.
  39    - Name constants using ##UPPERCASE##.
  40    - Write ##true##, ##false##, and ##null## in lowercase.
  41    - "Internal" methods and properties should be prefixed with an underscore.
  42      For more information about what "internal" means, see
  43      **Leading Underscores**, below.
  44  
  45  = Comments =
  46  
  47    - Strongly prefer ##//## comments for making comments inside the bodies of
  48      functions and methods (this lets someone easily comment out a block of code
  49      while debugging later).
  50  
  51  = Javascript Language =
  52  
  53    - Use ##[]## and ##{}##, not ##new Array## and ##new Object##.
  54    - When creating an object literal, do not quote keys unless required.
  55  
  56  = Examples =
  57  
  58  **if/else:**
  59  
  60    lang=js
  61    if (x > 3) {
  62      // ...
  63    } else if (x === null) {
  64      // ...
  65    } else {
  66      // ...
  67    }
  68  
  69  You should always put braces around the body of an if clause, even if it is only
  70  one line. Note that operators like ##>## and ##===## are also surrounded by
  71  spaces.
  72  
  73  **for (iteration):**
  74  
  75    lang=js
  76    for (var ii = 0; ii < 10; ii++) {
  77      // ...
  78    }
  79  
  80  Prefer ii, jj, kk, etc., as iterators, since they're easier to pick out
  81  visually and react better to "Find Next..." in editors.
  82  
  83  **for (enumeration):**
  84  
  85    lang=js
  86    for (var k in obj) {
  87      // ...
  88    }
  89  
  90  Make sure you use enumeration only on Objects, not on Arrays. For more details,
  91  see @{article:Javascript Object and Array}.
  92  
  93  **switch:**
  94  
  95    lang=js
  96    switch (x) {
  97      case 1:
  98        // ...
  99        break;
 100      case 2:
 101        if (flag) {
 102          break;
 103        }
 104        break;
 105      default:
 106        // ...
 107        break;
 108    }
 109  
 110  `break` statements should be indented to block level. If you don't push them
 111  in, you end up with an inconsistent rule for conditional ##break## statements,
 112  as in the ##2## case.
 113  
 114  If you insist on having a "fall through" case that does not end with ##break##,
 115  make it clear in a comment that you wrote this intentionally. For instance:
 116  
 117    lang=js
 118    switch (x) {
 119      case 1:
 120        // ...
 121        // Fall through...
 122      case 2:
 123        //...
 124        break;
 125    }
 126  
 127  = Leading Underscores =
 128  
 129  By convention, methods names which start with a leading underscore are
 130  considered "internal", which (roughly) means "private". The critical difference
 131  is that this is treated as a signal to Javascript processing scripts that a
 132  symbol is safe to rename since it is not referenced outside the current file.
 133  
 134  The upshot here is:
 135  
 136    - name internal methods which shouldn't be called outside of a file's scope
 137      with a leading underscore; and
 138    - **never** call an internal method from another file.
 139  
 140  If you treat them as though they were "private", you won't run into problems.