规范代码命名，让你的代码阅读起来更愉悦！

作者：岛上码农

2022 年 8 月 25 日
湖南
本文字数：2030 字
阅读完需：约 7 分钟

前言

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

标识符定义

大写驼峰，例如 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();
@fooclass 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

复制代码

总结

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

发布于: 2022 年 08 月 25 日阅读数: 79

原文链接:【http://xie.infoq.cn/article/efc95501042f96b38ba20a29a】。文章转载请联系作者。

岛上码农

关注

用代码连接孤岛，公众号@岛上码农 2022.03.03 加入

从南漂到北，从北漂到南的业余码农

发布

暂无评论

创作场景

规范代码命名，让你的代码阅读起来更愉悦！

前言

标识符定义

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

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

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

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

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

命名规则 6：缩写命名规则

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

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

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

总结

岛上码农

评论