Update the Style Guide

src/site/articles/style-guide/index.markdown

 ---
 layout: article
 title: "Dart Style Guide"
 rel:
   author: bob-nystrom
 description: "Follow these guidelines for consistent, readable Dart code."
 has-permalinks: true
 article:
   written_on: 2011-10-27
   updated_on: 2015-02-17
@@ skipping 588 matching lines @@
 }
 {% endprettify %}
 </div>
 
 
 ## Names
 
 #### DO name types using `UpperCamelCase`.
 {:.no_toc}
 
-Classes and typedefs should capitalize the first letter of each word (including
-the first word), and use no separators.
+Classes, enums, and typedefs should capitalize the first letter of each word
+(including the first word), and use no separators.
 
 <div class="good" markdown="1">
 {% prettify dart %}
 class SliderMenu {
   // ...
 }
 
 class HttpRequest {
   // ...
 }
 
 typedef num Adder(num x, num y);
 {% endprettify %}
 </div>
 
 
 #### PREFER using `lowerCamelCase` for constant names.
 {:.no_toc}
 <!-- https://github.com/dart-lang/www.dartlang.org/issues/831 -->
 
-In new code, use `lowerCamelCase` for constant variables.
+In new code, use `lowerCamelCase` for constant variables, including enum
+values.
 
 In existing code that uses `ALL_CAPS_WITH_UNDERSCORES` for constants, you
 may continue to use all caps to stay consistent.
 
 <div class="good">
 {% prettify dart %}
 const pi = 3.14;
 const defaultTimeout = 1000;
 final urlScheme = new RegExp('^([a-z]+):');
 
@@ skipping 360 matching lines @@
 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. Do you really need to call that class
 `AbstractWidgetFactoryManagerBuilder`?
 
 
-#### DO place the operator on the preceding line in a multi-line expression.
+#### DO place binary operators on the preceding line in a multi-line expression.
 {:.no_toc}
 
 There are valid arguments for both styles but most of our code seems to go this
 way, and consistency matters most.
 
 <div class="good">
 {% prettify dart %}
 if (isDeepFried ||
     (hasPieCrust && !vegan) ||
     containsBacon) {
@@ skipping 12 matching lines @@
 </div>
 
 <div class="bad">
 {% prettify dart %}
 bobLikes()
     => isDeepFried || (hasPieCrust && !vegan) || containsBacon;
 {% endprettify %}
 </div>
 
 
+#### DO place ternary operators on the next line in a multi-line expression.
+{:.no_toc}
+
+Also, if you break the line before one of the operators, prefer breaking
+around both.
+
+<div class="good">
+{% prettify dart %}
+return someCondition
+    ? whenTrue
+    : whenFalse;
+{% endprettify %}
+</div>
+
+<div class="bad">
+{% prettify dart %}
+return someCondition ?
+    whenTrue : whenFalse;

[Bob Nystrom, 2015/02/26 00:19:52]

Let's make this one:

return someCondition
  ? whenTrue : whenFalse;

[Kathy Walrath, 2015/02/26 16:15:14]

Done.

+return someCondition ?
+    whenTrue :
+    whenFalse;
+{% endprettify %}

[Bob Nystrom, 2015/02/26 00:19:52]

Also, maybe swap the order of the bad examples so they match the order of the
guidelines?

[Kathy Walrath, 2015/02/26 16:15:14]

Done.

+</div>
+
+
 #### DO place the `.` on the next line in a multi-line expression.
 {:.no_toc}
 
 This supercedes the previous rule. Unlike other operators, if you split an
 expression on a `.`, then put that at the beginning of the second line.
 
 <div class="good">
 {% prettify dart %}
 someVeryLongVariable.withAVeryLongProperty
     .aMethodOnThatObject();
@@ skipping 465 matching lines @@
 'Wear your wildest ${decade}s outfit.'
 {% endprettify %}
 </div>
 
 <div class="bad">
 {% prettify dart %}
 'Hi, ${name}!'
 "Wear your wildest ${decade}'s outfit."
 {% endprettify %}
 </div>
+
+
+## Ordering
+
+#### DO specify dart: imports, then package: imports, and then relative imports
+{:.no_toc}
+
+Separate import sections from each other with a single blank line.
+
+Within each section, prefer sorting alphabetically. If you use a
+`package:` import to import from your own package, consider putting
+that import in the relative import section.
+
+<div class="good">
+{% prettify dart %}
+import 'dart:async';
+import 'dart:convert' show JSON;
+import 'dart:html';
+
+import 'package:bar/bar.dart'
+import 'package:bar/foo.dart'
+import 'package:foo/bar.dart'
+
+import 'a.dart';
+{% endprettify %}
+</div>
+
+<div class="bad">
+{% prettify dart %}
+import 'dart:html';
+import 'dart:async';
+import 'dart:convert' show JSON;
+
+import 'a.dart';
+import 'package:bar/bar.dart'
+import 'package:foo/bar.dart'
+import 'package:bar/foo.dart'
+{% endprettify %}
+</div>
+
+#### PREFER specifying exports in a separate section after all imports
+{:.no_toc}
+
+Put a single blank line above the exports section.
+
+<div class="good">
+{% prettify dart %}
+import 'src/error.dart';
+import 'src/string_source.dart';
+
+export 'src/error.dart';
+{% endprettify %}
+</div>
+
+<div class="bad">
+{% prettify dart %}
+import 'src/error.dart';
+export 'src/error.dart';
+
+import 'src/string_source.dart';
+{% endprettify %}
+</div>
+
+
+#### PREFER specifying a name for every library
+{:.no_toc}
+
+Although Dart allows you to omit `library` from an app file
+(a file that has a top-level `main()` function)
+we recommend always specifying a library name.

[Bob Nystrom, 2015/02/26 00:19:52]

We do?

[Kathy Walrath, 2015/02/26 16:15:14]

I was surprised, too, but that was in seanegan's suggested wording
(https://github.com/dart-lang/www.dartlang.org/issues/635#issuecomment-74520529),
which you said sounded good to you.

I've taken it out. 

[Bob Nystrom, 2015/02/26 20:52:03]

My reading comprehension was bad. :(

I like the rest of Sean's comments but I don't think there's much value in
encouraging library names. They're 90% pointless. When the language does require
them (because you import two unnamed libraries), it will let you know.

+
+<div class="good">
+{% prettify dart %}
+library my_app;
+
+void main() {
+  ...
+}
+{% endprettify %}
+</div>
+
+<div class="bad">
+{% prettify dart %}
+void main() {
+  ...
+}
+{% endprettify %}
+</div>