What is a coding style guide?

A coding style guide is any rules for organization, variable naming and line space for myself while writing and updating the code.

Why not have a coding style guide?

Having a coding style often feels counter-productive. I want to command the machine, but not the machine to command my obedience to its rules unduly. I want to avoid an absolutely prescriptive format in source code, so I retain as much freedom as possible in my expressions and formats. Writers and developers should sufficiently prescribe their expressions to communicate successfully, so why should I go further?

Why have a coding style guide?

I like neat and predictable formatting, so I add a little more prescription in my expressions for lagniappe.

I also think having a coding style encourages more care during code review and shows consideration for others who read my code.

Coding style guideline

When dealing with version control, I sometimes look back at changes or review them before commit. Difference engines tend to choke on coding style changes, so it is important to limit and isolate coding style changes. When a file or files is or are first conformed to the coding style, I make it a separate commit so I don't drown out or obscure other changes.

Rules of space

We live in a universe of space, so some rules are in order!

  1. I trim trailing spaces from all lines.
  2. I store code files with consistent line ending style (Unix-style or Windows-style).
  3. I make consistent spacing around {} braces, () parentheses, [] brackets, <> chevrons, and other nesting containers such as <div>...</div> html5 start and end tags. I make a choice among the following styles frequently.
    1. I may place the open/left entity and corresponding close/right entity of a nesting container on a separate line. I increase the tab indent on the contained lines of code.
      • Preferred for code paths of control structures
      • Preferred for large structures
      Content block header...
      {
      	Contents...
      	More contents...
      	{
      		Inner contents...
      	}
      }
      Content block footer...
      
    2. I may have a single space before and a single space after the open entity and the close entity.
      • Preferred for a nesting container that contains nesting containers
      Cares["Too MUCH"] && ( Happy["Go Lucky"] + Sad["Out of Luck"] == Business['As Usual'] ) && continue;
    3. I may have a single space before and a single space after the nesting container, but have no space separating the open entity nor the close entity from what is contained.
      • Preferred for nesting containers that change order of operations
      • Preferred for small structures
      A * (B + C + D) + E
    4. I may have no space before nor after the open and close entities.
      • Preferred for function call parameter lists
      • Preferred for small units of code
      • Preferred for array indexing
      eatSome(giblets);
    5. Other spacing rules may override
  4. I make consistent choices of spacing around ; , list separators, and other separators of sequential items such as separators in ? : ternary operators.
    1. I may have no space before and a new line after. With list items on separate lines, I maintain consistent indent for each item.
      • Preferred for large nested structures
      [
      	"Apples",
      	"Bananas",
      	"Grapes",
      	[
      		"Papayas",
      		"Mangos"
      	]
      ]
      
    2. I may have a space before and a space after.
      • Preferred for lists of items that themselves have spaces
      getSome(54 , makeChoice("blueberries", "apples") , "and then go")
    3. I may have no space before nor after.
      • Preferred for huge lists
      • Preferred for machine-parsed auto-generated lists
      [1253,2151,23515,894,2198,354984,319846,19816,4984,1,61891,91,3516,84981,91351,918]
    4. I may have no space before and a space after. With list items on the same line, I maintain consistent single spacing for each list item.
      • Preferred for small structures
      getSome("stuff", 44, obj)
  5. I make consistent choices of spacing around ++ -- ! unary operators.
    • I should not have space between an operator and operand
    • I should have a space between a unary operator and an adjacent operator
      itemCount++;
      obj.show(a++ + b);
      
  6. I make consistent choices of spacing around < > <= >= == != ! === !== || && boolean operators.
    1. I may have no space before nor after.
      • Preferred for small expressions
      if (a||b)
    2. I may have a space before and a space after.
      • Preferred for large/nested expressions
      if (a && (b || c))
  7. I make consistent choices of spacing around + - * / arithmetic operators and | & ~ ^ << >> bitwise operators.
    1. I may have no space before nor after.
      • Preferred for small expressions
      x=a+b;
    2. I may have a space before and a space after.
      • Preferred for large/nested expressions
      x = a + b * (c + d);
  8. I make consistent choices of spacing around = += -= *= /= |= &= assignment operators.
    1. I may have no space before nor after.
      • Preferred for small expressions
      x+=a;
    2. I may have a space before and a space after.
      • Preferred for large/nested expressions
      x *= Math.Sin(Math.PI/2);
  9. I make consistent choice of spacing around with var function this scope control words.
    1. Generally, I should begin a new line for scope control words which begin statements.
    2. Generally, I should have space after scope control words.
    3. I should have no space after scope control words followed by a . ( ) dot or parentheses.
  10. I make consistent choice of spacing around if else do while for try catch switch case goto default continue break flow control words.
    1. I should begin a new line for flow control words.
    2. I should avoid space and expressions on the same line following else do try default continue break parameterless control words.
    3. I should have a space after if while for catch switch control words with parenthesized parameters.
    4. I should have a space after case goto control words with labels.

Rules of variable names

I have rules for variable names to make them easier to create, remember, and predict.

  1. I make consistent choice of capitalizing the first letter.
    1. I may capitalize the first letter.
      • Preferred for object classes and respective filenames.
    2. I may not capitalize the first letter.
      • Preferred for functions, most variables, properties and local variables.
    3. I may have a non-alphabetic first character.
      • Avoid.
  2. I make consistent choice of word formation in names.
    1. I may have a multi-word name.
      • Preferred for prototypes, classes, global functions, complex properties, and complex local variables
    2. I may have a single-word name.
      • Preferred for class/prototype inherited functions, properties, attributes, and local variables.
    3. I may have a single-letter or two-letter name.
      • Preferred for temporary, localized and loop variables.
  3. I make consistent choice on how to break words in names.
    1. I may capitalize the first letter of each word or acronym (known as camel case). First word is capitalized according to rules above.
      • Preferred style
    2. I may separate words with - a dash.
      • Preferred for names of CSS classes, servers, directories, files, and URLs.
    3. I may separate words with _ an underscore.
      • Preferred when - dash is not allowed
    4. I should avoid space as a word separator.
    5. I should avoid mixed/inconsistent separators in names.

Rules of organization

I have rules on code organization to locate specific or new code more easily.

  1. I group code into functions, then code sections, then files, then folders, then repositories, and then servers. I make divisions as follows.
    functions
    Divided according to encapsulation.
    Grouped to maintain proximity of variables and execution sequence.
    sections
    Divided according to independence of references and debugging.
    files
    Divided according to independence of creation, maintenance and consumption.
    folders
    Divided according to independence of review, copying and backup.
    repositories
    Divided according to independence of purpose, tracking, authorship and collaboration.
    servers
    Divided according to independence of ownership, protection, and management.
  2. I make consistent choice of encapsulating blocks of code.
    1. I should encapsulate each flow-controlled statement in a block so I can read and maintain the code more easily despite encapsulation being optional for controlling single statements. I add {} braces to match every if else for while do regardless except when paired together.
      for (;obj; obj = obj.next())
      {
      	if (!obj.hasOwnProperty("value"))
      	{
      		continue;
      	}
      	else if (obj.value < 10)
      	{
      		showSmall(obj);
      	}
      	else
      	{
      		showLarge(obj);
      	}
      }
      
    2. Though not advisable, I occasionally opt not to encapsulate even for multiple statements by a neat trick of javascript. I join several statements with another separator besides ; the semicolon such as , && || comma, boolean and, or boolean or that evaluates sequentially, so several statements act as one.