400 Conventions

Page Table of Contents

• Introduction
• Naming Conventions
• Doc Comments
• Strings
• Bracket Hell
• File structure with BLoC
• Performance Pitfalls

Introduction

//Last Fig 25 //Last Snip 42

I want to start this chapter of with a great quote from Dart’s official style guide:

“A surprisingly important part of good code is good style. Consistent naming, ordering, and formatting helps code that is the same look the same.” [1]

This chapter will teach you some of the current best practices and conventions when wirting Dart [2] code and Flutter [3] applications in general. That being said, the Dart team has published their own comprehensive guide [1] on writing effective Dart. I will be highlighting some of the information of that guide here, but I will mainly be focusing on the aspects that are unique to Dart and might be a bit counter intuitive when coming from a languages like Java [4].

Naming Conventions

There is three types of naming schemes in Dart. The following table is a summarie of when to use which of those schemes:

Nameing Scheme	When to use
lowercase_with_underscores	libraries, packages, directories, source files, and import prefixes: import 'package:js/js.dart' as js;
UpperCamelCase	classes, enums, type definitions, and type parameters
lowerCamelCase	anything else: Class members, top-level definitions, variables, parameters, constants

Table 2: Nameing Convention [1]

Most of those cases should look very familiar. But there are two things I want to highlight about constant values: Firstly, the Dart style guide discourages the use of all uppercase or SCREENING_CAPS. In most other languages all uppercase is used for constant values. The Dart team argues that during development you often end up changing constant variables to no longer be constant. When using all uppercase this leads to a lot of renaming. So the convention in Dart is to use the same scheme for every variable. Secondly, the official style guide forbids the use of prefixed like “k” for constants or any other variation of Hungarian Notaion [5]. They argue we are now able to see the type, scope, mutability, and other properties of our variables through the IDE and/or framework, and we no longer need to imbed such information into the name. It is iteresting to note that the official Flutter repository uses and encourages the use of a “k” prefix for constants in their style guide [6]. So I would argue that either approach is fine as long as you are consistent.

A few additional things to note about naming conventions in Dart [1]:

• a leading "_" is reserved to define a private scope, so you can’t use it for other purposes then that.
• Only capitalize the first letter of an Abbreviation For Example: ApiSupplier
• Whenever naming anything, ask your self: “Does each word in that type name tell me something critical or prevent a name collision?”, If not, shorten it.
• The last word of a class or variable should always be the most descriptive of what it is: PageCount & DataSink are better then NumberOfPage & DataIn

Doc Comments

In the snippets up until now you might have noticed the us of /// for comments. In Dart tripple-dash or “Doc Comments” are a replacement for the classical /** ... */ bloc comment from other language. The Dart team argues, that Doc Comments don’t take up two additional lines when suing them as a block comment:

/**
* Holds one pice of supreme [Wisdom]
*
* [Wisdom.id] is only unique in the scope of its [Wisdom.type].
*/
class Wisdom {...}

Code Snippet XXX: Classic Block comment

///Holds one pice of supreme [Wisdom]
///
///[Wisdom.id] is only unique in the scope of its [Wisdom.type].
class Wisdom {...}

Code Snippet XXX: Tripple-Dash Block comment

Wether you agree with that reasoning or not. You should definitely use them, because they can be used to auto generate a documentaion for your project with the Dartdoc tool [7] and they are shown as tooltips in your IDE:

Figure XXX: Wisgen Wisdom Tool Tip [8]

Some additional things to note about Doc Comments in Dart are [1]:

• They should always start with a one sentence description of what the commented thing dose. Preferably starting with a third person verb like Supplies, Holds, Models.
• That initial line should be followed by one empty line to make it stand out.
• Highlight relevant classes, functions or members by surrounding them with […].
  • They will be linked in the auto-generated docs
• Markdown [9] is supported for tripple-dash comments, so consider adding code snippets as examples.
• Don’t document information that is already obvious by class name and parameter:

///Adds the [int] values of [Adder.a] and [Adder.b] together.
Adder {
  int a;
  int b;
  Adder(this.a, this.b);
  ...
}

Code Snippet XXX: Redundant Doc Comment

Strings

• ${year + day}

Bracket Hell

• Own widgets (performance)
• Callback functions

File structure with BLoC

• no consensus, I would recommend a folder / layer + models
• ui into pages and widgets

lib
|
├── blocs
├── data
├── models
├── repositories
├── ui 
|   ├── pages
|   |   ├── home_page.dart
|   |   └── ...
|   └── widgets
|       ├── image_card.dart
|       └── ...
└── main.dart

Figure XXX: Possible Project File Structure

Performance Pitfalls

• short list of tips

Next Chapter: Conclusion >

Back to Top