“Curly-Brace” Languages

Many languages derive their look and feel from C, the original “curly-brace” language. Thus, because of this common provenance, a number of guidelines are applicable to all of them. These guidelines are listed here. Language-specific guidelines can be found on their respective individual language pages.

(duh)

Java

JavaScript

curly-1tbs: Keep opening curly braces on the same line as the code that precedes them.

Oh Yes We Did

Yes, we are explicitly choosing “1TBS” over “Allman-style” brace formatting.

Reason

Curly braces are a parsing necessary evil. In the absence of significant whitespace (as in Python), a language needs unambiguous delimiters for code boundaries. Well-presented code uses other signs, particularly whitespace, to indicate these boundaries, but curly-brace parsers are typically “blind” to those signs. Thus, the braces have to be there but they don’t have to be given any more presentational importance than they deserve.

Example

  if (codeIsFormattedWell) {
      thereIsLessConfusion();
      errorsAreLessLikely();
  }

Anti-Example

  while (openingCurlyBraces)
  {
      appearOnTheirOwn();
      thePrecedingCodeIsLessConnected();
      toWhatComesAfter();
  }

curly-brk: Always linebreak and indent clauses, even one-liners, and always delimit them with braces.

Reason

Presenting short clauses in a single line, and varying when to delimit them with braces, merely complicates the choices you make in how code is formatted and can lead to unintended errors.

Example

  while (aClauseHasOneLine) {
      alwaysUseBracesAndLinebreaksAndIndent();
  }

Anti-Examples

  if (iAmAskingForTrouble)
      thenIWillGetIntoTrouble();

  for (String excuse: excuses) youMightAddAnotherStatementOneDay();

Real-World Case

Failure to follow this practice contributed to the OS X Goto Fail vulnerability of 2014:

curly-mult: In multi-clause statements, keep the opening brace of the next clause on the same line as the closing brace of the previous one.

Reason

Doing this visually preserves the structure of the code: a multi-clause statement is still a single statement, and so it should look like one.

Example

  if (thisHasAnElseClause) {
      thenUseTheBraces();
      asGlue();
  } else {
      thereMayBeConfusion();
      thatWouldHaveBeenEasyToAvoid();
  }

Anti-Example

  try {
      notToSeparate();
      multipartStatements();
  }

  catch (MisinterprentationException me) {
      becauseThis();
      doesNotRepresentWhatTheyMean();
  }

curly-space: In general, add a space before and after braces. Notable exceptions include when they are adjacent to same-sided parentheses, at the beginning or end of a line, or preceding punctuation.

Reason

This continues the theme of reinforcing visually the structure of the code. Appropriate spacing keeps semantic entities distinct and prevents code from looking cluttered.

Example

  while (aBraceFollowsAParenthetical) {
      placeASpaceInBetweenThem();
      toAvoidConfusion();
  }

  aOneLineLiteral = { "less", "cluttered", "with", "spaces" };

Anti-Example

  try{
      toIncludeSpaces();
      beforeAndAfterBraces();
      inAppropriatePlaces();
  }catch (ClutterException ce){
      becauseWithoutThem();
      distinctElements();
      standOutLess();
  }

curly-rsrv: Include a space before and after reserved words like if, while, return, etc.

Reason

Reserved words are part of the language and are neither functions, nor variables, nor other expressions. Adding a space keeps them from being misread as any of these.

Observation

If the character after a reserved word is not punctuation, you must insert a space anyway. This guideline keeps the rules consistent across the board.

Example

  for (int i = aReservedWord; i !== identifier; i += 1) {
      surroundThemWithSpaces();
      if (notSurrounded) {
          return potentialMisreading;
      }
  }

Anti-Example

  while(isNotAFunction) {
      butItMightLookLikeOne();
      ifThereIsNoSpaceAfterIt();
  }

  try{
      theLineAboveIsAlsoCoveredByCurlySpace();
  } catch(NotAFunctionException nafe) {
      returnthisLineWillNotCompileWithoutASpace;
  }