Formatting

DO

DO format your code using dartfmt

Formatting is tedious work and is particularly time-consuming during refactoring. Fortunately, you don’t have to worry about it. We provide a sophisticated automated code formatter called  dartfmt that does it for you. We have some documentation on the rules it applies, but the official whitespace-handling rules for Dart are whatever dartfmt produces. 

The remaining formatting guidelines are for the few things dartfmt cannot fix for you

DO use curly braces for all flow control statements

Doing so avoids the dangling else problem.

if (isWeekDay) { 
   print('Bike to work!'); 
} else { 
   print('Go dancing or read a book!'); 
}

Exception: When you have an if statement with no else clause and the whole if statement fits on one line, you can omit the braces if you prefer:

if (arg == null) return defaultValue;

If the body wraps to the next line, though, use braces:

if (overflowChars != other.overflowChars) { 
   return overflowChars < other.overflowChars; 
}

CONSIDER

CONSIDER changing your code to make it more formatter-friendly

The formatter does the best it can with whatever code you throw at it, but it can’t work miracles. If your code has particularly long identifiers, deeply nested expressions, a mixture of different kinds of operators, etc. the formatted output may still be hard to read.

When that happens, reorganize or simplify your code. Consider shortening a local variable name or hoisting out an expression into a new local variable. In other words, make the same kinds of modifications that you’d make if you were formatting the code by hand and trying to make it more readable. Think of dartfmt as a partnership where you work together, sometimes iteratively, to produce beautiful code.

AVOID

AVOID lines longer than 80 characters

Readability studies show that long lines of text are harder to read because your eye has to travel farther when moving to the beginning of the next line. This is why newspapers and magazines use multiple columns of text.

If you really find yourself wanting lines longer than 80 characters, our experience is that your code is likely too verbose and could be a little more compact. The main offender is usually VeryLongCamelCaseClassNames. Ask yourself, “Does each word in that type name tell me something critical or prevent a name collision?” If not, consider omitting it.

Note that dartfmt does 99% of this for you, but the last 1% is you. It does not split long string literals to fit in 80 columns, so you have to do that manually.

Exception: When a URI or file path occurs in a comment or string (usually in an import or export), it may remain whole even if it causes the line to go over 80 characters. This makes it easier to search source files for a path.

Exception: Multi-line strings can contain lines longer than 80 characters because newlines are significant inside the string and splitting the lines into shorter ones can alter the program.