规范代码命名,让你的 Dart 代码阅读起来更愉悦!

8,268 阅读5分钟

「这是我参与11月更文挑战的第11天,活动详情查看:2021最后一次更文挑战

前言

好的编码风格非常重要,保持一致的命名能够让代码阅读体验更好,能够让团队协作的效率更高。本篇介绍一下官方推荐的命名规范。

标识符定义

  • 大写驼峰,例如UpperCamelCase,每个单词的首字母大写。
  • 小写驼峰,例如 lowerCamelCase,第一个单词全部小写,之后每个单词的首字母大写。
  • 使用下划线“_”拼接全部小写单词,例如 lowercase_with_underscores。

命名规则1:统一使用大写驼峰命名类型

例如类、枚举、别名(typedefs)等使用大写驼峰,并且不使用分隔符。下面是示例:

class SliderMenu { ... }

class HttpRequest { ... }

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

包括携带参数注解也应该遵循这样的原则:

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

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

@Foo()
class B { ... }

如果注解没有携带参数,那么可以使用小写驼峰的方式。

const foo = Foo();

@foo
class C { ... }

命名规则2:类扩展使用大写驼峰

和类型一样,类扩展定义也应该使用大写驼峰:

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

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

命名规则3:库、包名、目录和源文件应当使用下划线“_”拼接小写单词

由于某些文件系统不区分大小写,而有的系统是区分的。因此很多项目要求文件名全部小写。这种情况下使用分隔符可读性会更高。下面是示例对比:

// 正确示例
library peg_parser.source_scanner;

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

// 错误示例
library pegparser.SourceScanner;

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

命名规则4:import 的别名使用下划线“_”拼接小写单词

当你要对引入的包或插件重命名时,应当使用下划线“_”拼接小写单词的形式。

// 正确示例
import 'dart:math' as math;
import 'package:angular_components/angular_components'
    as angular_components;
import 'package:js/js.dart' as js;

// 错误示例
import 'dart:math' as Math;
import 'package:angular_components/angular_components'
    as angularComponents;
import 'package:js/js.dart' as JS;

命名规则5:变量名、类成员属性、参数和常量使用小写驼峰

类的成员属性、变量、函数参数、顶级定义参数和命名参数都应该使用小写驼峰方式。

// 正确示例
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();
}

// 错误示例
const PI = 3.14;
const DefaultTimeout = 1000;
final URL_SCHEME = RegExp('^([a-z]+):');

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

这里需要注意,很多语言都推荐常量使用下划线+全部大写字母的方式定义,但是 Dart 推荐的是小写驼峰形式。这是因为大多数情况下全部大写的可读性差,尤其是对于像 CSS 颜色那样的枚举值;常量有可能会更改为普通变量,这样可能增加名称修改。

命名规则6:缩写命名规则

对于缩写单词,如果字符多的时候全部大写会很奇怪,例如 HTTPSFTP 这样看起来显然没有 HttpsFtp 的可读性好。但是对于那种两个字母的缩写,推荐根据可读性决定是否要全部大写还是大写驼峰,比如 IO这类通用的可以写成 IO,而ID 的话写成 Id 可读性也不差。下面是一个对比示例。

// 正确示例
class HttpConnection {}
class DBIOPort {}
class TVVcr {}
class MrRogers {}

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

// 错误示例
class HTTPConnection {}
class DbIoPort {}
class TvVcr {}
class MRRogers {}

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

命名规则7:参数列表中未使用的参数使用_,__标识

有些回调方法只使用部分参数,这个时候可以将未使用的参数使用下划线替换,明确表示这个参数不会使用。而如果有多个参数没被使用的话,可以依次使用多个下划线标识。下面是一个例子:

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

这个指导原则只适用于匿名方法或局部方法。而对于声明式函数不应该这么做,即便是不使用也需要有正确命名,以保持参数语义明确。

命名规则8:仅对私有类成员属性使用下划线标识。

Dart 使用下划线开头标识类成员为私有属性,顶级定义的变量是文件局部变量。因此仅对这类使用下划线标识。同时,对于局部变量、参数和局部方法这些并没有私有成员的概念,因此没必要使用下划线开头,避免引起误解。

命名规则9:不要使用前缀字母

有些编程语言会建议使用一些特殊的字母标识变量,例如数值类的使用 k 开头。这种约定一方面挺难持续遵循,而且对可读性的帮助也不大。下面是对应的示例:

// 正确示例
defaultTimeout

// 错误示例
kDefaultTimeout

总结

拥有良好且一致的命名风格能够让你的代码看起来更加舒服,愉悦。其实也是个人软实力的一个特征。记住一条,代码是写给人看的!

我是岛上码农,微信公众号同名,这是Flutter 入门与实战的专栏文章,提供体系化的 Flutter 学习文章。对应源码请看这里:Flutter 入门与实战专栏源码。如有问题可以加本人微信交流,微信号:island-coder。觉得有收获请按如下方式给个爱心三连

👍🏻:点个赞鼓励一下!

🌟:收藏文章,方便回看哦!

💬:评论交流,互相进步!