您想找什么?
Hero background image

在Unity中进行C#脚本的格式化最佳实践

为方便起见,此网页已进行机器翻译。我们无法保证翻译内容的准确性或可靠性。如果您对翻译内容的准确性有疑问,请参阅此网页的官方英文版本。

虽然可能没有一种正确的方式来格式化你的C#代码,但在团队中达成一致的风格可以使代码库更清晰、更易读且更具可扩展性。本页面提供了在创建自己的风格指南时,关于类、方法和注释的一些提示和关键考虑事项。

注意:这里分享的建议基于微软提供的建议。最佳的代码风格指南规则是适合你团队需求的规则。

你可以在这里找到一个代码风格指南示例,或下载完整的电子书,创建C#风格指南:编写可扩展的更清晰的代码

格式化你的代码

与命名一起,格式化有助于减少猜测并提高代码清晰度。通过遵循标准化的风格指南,代码审查变得不再关注代码的外观,而是关注代码的功能。

旨在个性化您的团队格式化代码的方式。在设置您的Unity风格指南时,请考虑以下每个代码格式化建议。您可以选择省略、扩展或修改这些示例规则以适应您团队的需求。

在所有情况下,反思您的团队将如何实施每个格式化规则,然后让每个人统一应用它。参考您团队的风格指南以解决任何不一致之处。您越少考虑格式化,您就能越高效和创造性地工作。

让我们看看一些格式化指南。

属性

属性提供了一种灵活的机制来读取、写入或计算类值。属性的行为就像它们是公共成员变量,但实际上它们是称为访问器的特殊方法。

每个属性都有一个获取和设置方法来访问一个私有字段,称为后备字段。通过这种方式,属性封装数据,将其隐藏以防止用户或外部对象的意外更改。“获取器”和“设置器”各自有自己的访问修饰符,允许您的属性为可读写只读只写

您还可以使用访问器来验证或转换数据(例如,验证数据是否符合您首选的格式或将值更改为特定单位)。

属性的语法可能会有所不同,因此您的风格指南应定义如何格式化它们。请参阅以下示例以获取有关如何在代码中保持属性一致性的提示。

表达式主体属性

对于单行只读属性(=>)使用表达式主体属性:这将返回私有后备字段。

自动实现的属性

其他所有内容使用表达式主体 { get; set; } 语法:如果您只想公开一个公共属性而不指定后备字段,请使用自动实现属性

为设置和获取访问器应用表达式主体语法。如果您不想提供写访问权限,请记得将“setter”设为私有。对齐多行代码块的闭合括号与开括号。

可序列化类
可序列化类或结构可以帮助组织检查器。

序列化

脚本序列化是将数据结构或对象状态转换为 Unity 可以存储和稍后重建的格式的自动过程。出于性能原因,Unity 的序列化处理方式与其他编程环境不同。

序列化字段出现在 检查器 中,但您不能序列化静态、常量或只读字段。它们必须是公共的或带有 [SerializeField] 属性。Unity 仅序列化某些字段类型,因此请参考 文档 以获取完整的序列化规则。

在处理序列化字段时,请遵循以下基本指南:

使用 [SerializeField] 属性: SerializeField 属性可以与私有或受保护的变量一起使用,使其在检查器中显示。这比将变量标记为公共的方式更好地封装了数据,并防止外部对象覆盖其值。

使用 Range 属性设置最小值和最大值:如果您想限制用户可以分配给数值字段的内容,[Range(min, max)] 属性非常方便。它还方便地将字段表示为检查器中的滑块。

在可序列化类或结构中分组数据以清理检查器: 定义一个公共类或结构,并用 [Serializable] 属性标记它。为您希望在检查器中公开的每种类型定义公共变量。

从另一个类引用此可序列化类。结果变量在检查器中以可折叠单元的形式出现。

大括号或缩进风格

C#中有两种常见的缩进风格:

Allman风格,也称为BSD风格(来自BSD Unix),将打开的花括号放在新的一行。

K&R风格,或称为“唯一真实的花括号风格”,将打开的花括号与前一个头部放在同一行。

这些缩进风格也有变体。本指南中的示例使用来自Microsoft框架设计指南的Allman风格。无论你作为团队选择哪一种,确保每个人都遵循相同的缩进和花括号风格。你还可以尝试以下部分中的提示。

C Sharp选项卡
在WINDOWS的VISUAL STUDIO中的选项卡设置

决定统一的缩进方式

缩进通常为两个或四个空格。让你团队中的每个人在编辑器偏好设置中达成一致,而不引发选项卡与空格的争论

Windows的Visual Studio中,导航到工具 > 选项 > 文本编辑器 > C# > 选项卡

Mac的Visual Studio中,导航到偏好设置 > 源代码 > C#源代码。选择文本样式以调整设置。

注意:Visual Studio提供将选项卡转换为空格的选项。

不要省略大括号

不要省略花括号——即使是单行语句也不例外。花括号增加了一致性,使你的代码更易于阅读和维护。在这个例子中,花括号清楚地将动作DoSomething与循环分开。

如果你需要添加调试行或稍后运行DoSomethingElse,花括号将已经到位。将子句放在单独的行上可以让您简单地添加一个断点。

在多行语句中保留大括号以提高清晰度

不要从嵌套的多行语句中删除大括号。在这种情况下删除大括号不会抛出错误,但可能会导致混淆。即使大括号是可选的,也要使用大括号以提高清晰度。

标准化switch语句

格式可能会有所不同,因此请在您的风格指南中记录团队偏好,并相应地标准化您的 switch 语句。

这是缩进案例语句的一个示例。

水平间距

像空格这样简单的东西可以增强您代码在屏幕上的外观。虽然个人格式化偏好可能会有所不同,但请考虑以下建议以提高可读性。

添加空格

添加空格以减少代码密度。额外的空白给人一种视觉上分隔行内各部分的感觉。

逗号后的间距

在函数参数之间的逗号后使用一个空格。

括号后没有间距

在括号和函数参数后不要添加空格。

函数与括号之间没有空格

函数名称和括号之间不要使用空格。

避免在括号内留空格

尽量避免在括号内使用空格。

流程控制条件前的间距

在流程控制条件前使用一个空格,并在流程比较运算符和括号之间添加空格。

与比较运算符的间距

在比较运算符前后使用一个空格。

可读性提示

保持行短,并考虑水平空白。决定一个标准的行宽(80-120个字符),并将长行拆分为较小的语句,而不是让其溢出。

如前所述,尽量保持缩进/层次结构。缩进代码可以提高可读性。

除非为了可读性需要,否则不要使用列对齐。虽然这种类型的空格对齐了变量,但可能会使类型与名称的配对变得复杂。

然而,列对齐对于位运算表达式或包含大量数据的结构体可能是有用的。只需注意,随着您添加更多项目,维护列对齐可能会给您带来更多工作。一些自动格式化工具可能还会改变列的对齐部分。

垂直间距和区域

您也可以利用垂直空白。将相关的脚本部分放在一起,并利用空行。尝试以下方法将代码从上到下组织:

  • 将依赖或相似的方法分组在一起:代码需要逻辑性和连贯性。将执行相同操作的方法放在一起,以便阅读逻辑的人不必在文件中跳来跳去。
  • 使用垂直空白来分隔类的不同部分:例如,您可以在以下内容之间添加两行空白:
  • 变量声明和方法
  • 类和接口
  • if-then-else 块(如果有助于可读性)

将其保持在最低限度,如果可能的话,在您的风格指南中跟踪它。

在代码中使用区域

#region 指令使您能够折叠和隐藏 C# 文件中的代码部分,使大型文件更易于管理和阅读。

然而,如果您遵循本指南中关于类的一般建议,您的类大小应该是可管理的,#region 指令则是多余的。将代码分解为更小的类,而不是将代码块隐藏在区域后面。如果源文件较短,您将不太倾向于添加区域。

注意:许多开发人员认为区域是 代码异味或反模式。作为一个团队决定您站在辩论的哪一方。

C# 偏好
预览窗口展示了您的风格指南选择。

Visual Studio 中的代码格式化

如果这些格式规则看起来令人不知所措,不要绝望。现代 IDE 使设置和强制执行它们变得高效。您可以创建格式规则的模板,然后一次性转换项目文件。

要为脚本编辑器设置格式规则:

  • Windows 的 Visual Studio 中,导航到 工具 > 选项,然后找到 文本编辑器 > C# > 代码样式格式化
  • 使用设置来修改 常规、缩进、新行、间距和换行 选项。
  • Mac 的 Visual Studio 中,选择 Visual Studio > 偏好设置,然后导航到 源代码 > 代码格式化 > C# 源代码
  • 在顶部选择 策略,然后转到 文本样式 选项卡。在 C# 格式 选项卡中,调整 缩进、新行、间距和换行设置

要强制您的脚本文件符合样式指南:

  • Windows 的 Visual Studio 中,转到 Edit > 高级 > 格式文档 (Ctrl + K, Ctrl + D 快捷键组合)。如果您只想格式化空格和制表符对齐,您还可以在编辑器底部使用 运行代码清理 (Ctrl + K , Ctrl + E)
  • Mac 的 Visual Studio 中,转到 编辑 > 格式文档 (Ctrl + I 快捷键)。

在 Windows 上,您还可以从 工具 > 导入和导出设置 共享您的编辑器设置。导出一个包含样式指南的 C# 代码格式的文件,然后让每个团队成员导入该文件。

Visual Studio 帮助您遵循样式指南。格式化变得像使用快捷键一样简单。

注意:您可以配置一个 EditorConfig 文件(见上文),而不是导入和导出 Visual Studio 设置。这样可以方便地在不同的 IDE 之间共享格式。它还具有与版本控制一起工作的额外好处。有关更多信息,请参见 .NET 代码样式规则选项

虽然这并不特定于干净代码,但请务必查看 在 Unity 中使用 Visual Studio 加速编程工作流程的 10 种方法。请记住,如果您应用这些生产力技巧,格式化和重构干净代码会更方便。

获取更多代码风格提示

了解更多关于命名约定 在这里 或查看 完整电子书。您还可以查看我们的详细 代码风格指南示例