Standardize code naming to make your Dart code more pleasant to read

Click here to learn about the "Flutter Introduction and Combat" column, continuous update and systematic learning!

foreword

Good coding style is very important. Keeping consistent naming can make the code reading experience better and team collaboration more efficient. This article introduces the officially recommended naming convention.

Identifier Definition

  • Upper CamelCase, such as UpperCamelCase, capitalizes the first letter of each word.
  • Lower camel case, such as lowerCamelCase, the first word is all lowercase, and the first letter of each word after that is capitalized.
  • Use underscore "_" to concatenate all lowercase words, eg lowercase_with_underscores.

Naming Rule 1: Use capital camel case to name types uniformly

For example, classes, enums, aliases (typedefs), etc. use upper camel case and do not use delimiters. Here is an example:

class SliderMenu { ... }

class HttpRequest { ... }

typedef Predicate<T> = bool Function(T value);

Including carrying parameter annotations should also follow this principle:

class Foo {
  const Foo([Object? arg]);
}

@Foo(anArg)
class A { ... }

@Foo()
class B { ... }

If the annotation does not carry parameters, then lower camel case can be used.

const foo = Foo();

@foo
class C { ... }

Naming Rule 2: Use upper camel case for class extensions

Like types, class extension definitions should use upper camel case:

extension MyFancyList<T> on List<T> { ... }

extension SmartIterable<T> on Iterable<T> { ... }

Naming Rule 3: Libraries, package names, directories and source files should use underscore "_" to concatenate lowercase words

Since some file systems are not case sensitive, others are. Therefore many projects require filenames to be all lowercase. Using delimiters in this case is more readable. Here is an example comparison:

// correct example
library peg_parser.source_scanner;

import 'file_system.dart';
import 'slider_menu.dart';

// Error example
library pegparser.SourceScanner;

import 'file-system.dart';
import 'SliderMenu.dart';

Naming Rule 4: Aliases of import use underscore "_" to concatenate lowercase words

When you want to rename an imported package or plugin, you should use the underscore "_" to concatenate lowercase words.

// correct example
import 'dart:math' as math;
import 'package:angular_components/angular_components'
    as angular_components;
import 'package:js/js.dart' as js;

// Error example
import 'dart:math' as Math;
import 'package:angular_components/angular_components'
    as angularComponents;
import 'package:js/js.dart' as JS;

Naming Rule 5: Use lower camel case for variable names, class member properties, parameters, and constants

Class member properties, variables, function parameters, top-level definition parameters, and named parameters should all use lower camel case.

// correct example
var count = 3;

HttpRequest httpRequest;

void align(bool clearItems) {
  // ...
}

const pi = 3.14;
const defaultTimeout = 1000;
final urlScheme = RegExp('^([a-z]+):');

class Dice {
  static final numberGenerator = Random();
}

// Error example
const PI = 3.14;
const DefaultTimeout = 1000;
final URL_SCHEME = RegExp('^([a-z]+):');

class Dice {
  static final NUMBER_GENERATOR = Random();
}

It should be noted here that many languages ​​recommend that constants be defined in the form of underscore + all uppercase letters, but Dart recommends lower camel case. This is due to the poor readability of all caps in most cases, especially for enum values ​​like CSS colors; constants may be changed to normal variables, which may increase name mangling.

Naming Rule 6: Abbreviation Naming Rule

For abbreviated words, if there are many characters, it will be very strange to all capitalize, such as HTTPSFTP, which obviously does not seem to be as readable as HttpsFtp. However, for the two-letter abbreviation, it is recommended to decide whether to use all uppercase or uppercase camel case according to readability. For example, general-purpose such as IO can be written as IO, and ID is written as Id, which is not bad for readability. Below is a comparative example.

// correct example
class HttpConnection {}
class DBIOPort {}
class TVVcr {}
class MrRogers {}

var httpRequest = ...
var uiHandler = ...
Id id;

// Error example
class HTTPConnection {}
class DbIoPort {}
class TvVcr {}
class MRRogers {}

var hTTPRequest = ...
var uIHandler = ...
ID iD;

Naming Rule 7: Unused parameters in the parameter list are identified with _, __

Some callback methods only use some parameters. In this case, you can replace the unused parameters with underscores to make it clear that the parameters will not be used. And if there are multiple parameters that are not used, multiple underscores can be used in sequence. Below is an example:

futureOfVoid.then((_) {
  print('Operation complete.');
});

This guideline only applies to anonymous or local methods. This should not be done for declarative functions, even if they are not used, they need to be properly named to keep the parameter semantics clear.

Naming Rule 8: Use underscores only for private class member properties.

Dart uses a leading underscore to identify class members as private properties, and variables defined at the top level are file-local variables. Therefore only use underscores for this class. At the same time, there is no concept of private members for local variables, parameters and local methods, so there is no need to start with an underscore to avoid misunderstandings.

Naming Rule 9: Don't use prefix letters

Some programming languages ​​suggest using some special letters to identify variables, such as numeric classes starting with k. This convention is hard to follow consistently and doesn't help readability much. Here is the corresponding example:

// correct example
defaultTimeout

// Error example
kDefaultTimeout

Summarize

Having a good and consistent naming style can make your code look more comfortable and pleasing. In fact, it is also a characteristic of personal soft power. Remember one, code is written for people to see!

Tags: Front-end Android Design Pattern Flutter dart

Posted by MBrody on Thu, 19 May 2022 02:17:31 +0300