[译]Effective Dart: Style

545 阅读6分钟

良好的代码风格至关重要。一致的命名规则,顺序结构和格式化有助于代码看起来相同。它利用了我们视觉系统的模式匹配能力。如果我们在整个Dart生态系统中使用一致的风格,那么我们所有人都可以更轻松地学习和修改彼此的代码。

标识符

  • 使用UpperCamelCase 命名类型.
  • 使用lowercase_with_underscores命名库和源文件.
  • 使用lowercase_with_underscores命名导入前缀.
  • 使用lowerCamelCase 命名其他标识符.
  • 推荐使用lowerCamelCase 命名常量.
  • 使用首字母大写和缩略词长度超过两个字母.
  • 不要使用字母前缀.

导入库顺序

  • “dart:”放在文件最上面.
  • “package:”放在相关库前面.
  • 推荐“third-party” “package:”放在其他库前面.
  • 在所有导入后,指定单独的部分.
  • 其他部分,按照字母顺序进行排序.

格式化

  • 使用dartfmt 格式化代码.
  • 考虑更改代码使其更容易格式化.
  • 避免每行超过80个字符.
  • 使用{}进行流程控制.

标识符

Dart中的标志符,有三种风格。

  • UpperCamelCase 每个单词的首字母大写,包括第一个单词.

  • lowerCamelCase 第一个单词首字母小写(即使是缩略词),其他单词的首字母大写.

  • lowercase_with_underscores 只使用小写字母,即使是首字母,缩略词,也只是用 _ 分隔.

使用UpperCamelCase 命名类型

类, 枚举, typedefs, 和 类型参数应该大写每个单词的首字母, 并使用分隔符.

1

甚至包括元数据注释

2

如果注释类的构造函数不带参数,则可能需要为其创建单独的lowerCamelCase常量。

使用lowercase_with_underscores命名库和源文件

某些文件系统不区分大小写,因此许多项目要求文件名全部为小写。 使用分隔字符可以确保可读性。使用下划线作为分隔符可确Dart标识符有效,如果Dart稍后支持符号导入,可以避免兼容问题。

Note: 如果使用标准规则命名库,你可以在库文件省略说明

使用lowercase_with_underscores命名导入前缀

使用lowerCamelCase 命名其他标识符

类成员,顶级定义,变量,参数和命名参数应该大写除第一个单词之外的每个单词的第一个字母,并且不使用分隔符。

推荐使用lowerCamelCase 命名常量

在新代码中,使用lowerCamelCase作为常量变量,包括枚举值。 在使用SCREAMING_CAPS的现有代码中,您可以继续使用全部大写以保持一致。

Note: 我们最初使用Java的SCREAMING_CAPS样式来表示常量。 但我们改变了,因为: -SCREAMING_CAPS在许多情况下都很糟糕,特别是像CSS颜色这样的枚举值. 。 在枚举类型上自动定义的values属性是const和lowercase。

  • 常量通常最终更改为非常量变量,这将需要更改名称.
  • 在枚举类型上自动定义变量属性是常量和 lowercase.

使用首字母大写和缩略词长度超过两个字母

大写的首字母缩略词可能难以阅读,而多个相邻的首字母缩略词可能会导致模糊的名称。 例如,如果名称以HTTPSFTP开头,则无法判断它是指HTTPS FTP还是HTTP SFTP。 为了避免这种情况,首字母缩略词和缩写词像普通词一样大写,除了两个字母的首字母缩略词。 (像ID和Mr.这样的两个字母的缩写仍然像文字一样大写。)

不要使用字母前缀

匈牙利命名法和其他方案出现在BCPL时,当时的编译器不能做太多,帮助您理解代码。 因为Dart可以告诉您声明的类型,作用域,可变性和其他属性,所以没有必要在标识符名称中对这些属性进行编码。

包导入顺序

为了使文件的序言保持整洁,我们有规定的出现顺序。每个“部分”用空行分隔。

“dart:”放在文件最上面

“package:”放在相关库前面

推荐“third-party” “package:”放在其他库前面

如果您导入许多自己的包和其他第三方包,请您在外部软件包之后加上空行进行分隔。

在所有导入后,指定单独的部分

其他部分,按照字母顺序进行排序.

格式化

像许多语言一样,Dart忽略空格。 但是,人类没有。具有一致的空样式有助于确保人类读者与编译器以相同方式查看代码。

使用dartfmt 格式化代码

格式化是一项繁琐的工作,在重构过程中特别耗时。 幸运的是,你不必担心它。 我们提供了一个名为dartfmt的复杂自动代码格式化程序,它可以为您完成。 我们提供了使用文档,但是Dart的官方空白处理规则是dartfmt产生的。

其余格式化指南,适用于dartfmt无法为您修复的一些内容。

考虑更改代码使其更容易格式化

格式化程序会对你写的代码竭尽全力,但它不是神。 如果您的代码具有特别长的标识符,深层嵌套的表达式,混合不同类型的运算符等问题,这样即使格式化,输出代码仍然难以阅读。

发生这种情况时,应该重新组织或简化您的代码。 考虑缩短局部变量名称或将表达式提升到新的局部变量中。 换句话说,如果您手动格式化代码并尝试使其更具可读性,请进行相同类型的修改。 当写代码时将dartfmt视为一种合作关系,有时可以迭代地生成漂亮的代码。

避免每行超过80个字符

可读性研究表明,长行文字难以阅读,因为当你移动到下一行的开头时,你的眼睛必须走得更远。 这就是为什么报纸和杂志使用多列文本。

如果你真的发现自己想要超过80个字符的行,我们的经验是你的代码可能过于冗长并且可能更紧凑。 主要问题通常是VeryLongCamelCaseClassNames。 问问自己,“该类型名称中的每个单词是否告诉我一些关键信息或防止名称冲突?”如果不是,请考虑省略它。

请注意,dartfmt会为您完成99%,但最后1%需要您完成。 它不会将长字符串文字拆分为80列,因此您必须手动执行此操作。

我们对URI和文件路径进行了额外处理。当这些出现在注释或字符串中时(通常在导入和导出中),即使超出行限制,它们也可能保留在一行中。这样可以更轻松地搜索指定路径的源文件。

使用{}进行流程控制

避免悬空问题

有一个例外:一个没有else子句的if语句,其中整个if语句和执行语句适合一行。 在这种情况下,如果您愿意,可以不用括号:

如果正文包裹到下一行,请使用大括号: