代码结构基础

前面几章我们已经跑了程序，但还没正式聊”一个 Swift 文件长什么样”。这一章补上这个底子：注释怎么写、import 是干嘛的、分号要不要、代码怎么组织。

1-1 一个最小的文件骨架

一个 Swift 文件，本质上是一堆”顶层语句”加”各种定义”的组合。最外层直接写的语句会从前往后执行。你也可以在里面定义常量、变量、函数、类型。

import Foundation

let appName = "我的小程序"
print("欢迎使用 \(appName)")

这里的 import Foundation 是引入一个标准库模块，let 定义常量，顶层 print 是程序要做的动作。整体结构清爽，没有类包裹、没有强制的入口函数。

1-2 import：把能力请进来

Swift 的功能被分装在”模块”里。标准库（Swift 模块）默认就在手边，所以 print、String、Int 这些你直接就能用。但有些能力放在别的模块，得先 import 才可用。

最常见的就是 Foundation，它提供了更丰富的字符串处理、日期、文件等能力。写了 import Foundation 后，你的 String 会额外获得很多方法（比如把字符串转成大写）。

import 的写法是关键字 import 后跟模块名：

import Foundation

后面学到更多模块时，import 会频繁出现。现阶段记住一句话：要用某个模块里的东西，先把它 import 进来。纯语言学习大多只需 Foundation，很多例子连它都不需要。

1-3 单行注释

注释是写给人看的说明，编译器会忽略它。Swift 的单行注释以双斜杠开头：

// 这一行是注释，编译器看不见
let score = 100 // 也可以写在代码后面

单行注释从 // 一直到行尾。它最适合标注某一行代码的意图，或者临时把一行代码”关掉”不运行。

1-4 多行注释

需要写大段说明时，用斜杠加星号开头、星号加斜杠结尾：

/*
这是多行注释，
可以跨好几行，
编译器全部忽略。
*/

多行注释常用于函数上方的功能说明，或临时屏蔽一整段代码。

1-5 Swift 注释的一个独门绝技

C 语言的多行注释不能嵌套，Swift 却可以。你可以在一段多行注释里再开一段多行注释：

/* 外层注释开始
    /* 这是被嵌套的内层注释 */
   外层注释结束 */

这个特性很实用：当你想临时注释掉一大段代码，而那段代码里本来就含有多行注释时，在 C 里会出错，在 Swift 里却没问题。初学者常靠它快速”关停”一块代码做对比试验。

1-6 文档注释 ///

三个斜杠 /// 是文档注释，专门用来给后面的类型、函数写说明。配合 IDE，调用处能直接显示这段说明：

/// 计算两个数的和
/// - Parameters: 接受两个整数
func add(_ a: Int, _ b: Int) -> Int {
    a + b
}

文档注释不影响运行，但能让代码更好维护。初学阶段了解即可，不必强求每处都写。

1-7 分号：可写可不写

Swift 不要求语句结尾加分号。一行一句时，直接回车就行：

let x = 1
let y = 2

只有当你坚持在同一行写多条语句，才必须用分号隔开：

let x = 1; let y = 2; print(x + y)

初学者的建议很明确：一行写一句，不写分号。这样代码最干净，也最符合 Swift 的习惯。等以后写特别紧凑的逻辑时，再视情况用分号。

1-8 文件与代码组织

在纯语言学习里，一个 .swift 文件就能装下很多内容。同一模块下的多个文件，顶层定义彼此可见，不需要互相 import；import 是用来把别的模块的能力请进来的。跨文件的精细组织靠的是”访问控制”，那是以后的话题。

现阶段你只要知道：每个 .swift 文件都是独立的一页纸，最外层的语句会被执行，里面的定义可以被同文件后续代码使用。把相关的练习放在一个文件里，是最省心的组织方式。

1-9 写注释与组织的小提醒

代码结构这些规矩，初看枯燥，却是你和团队协作、和未来自己读代码的基础。注释写给人看，编译器忽略它，所以注释贵在”说明为什么”而非”复述代码做了什么”。比如写 // 重试三次避免网络抖动 比 // 循环三次 有用得多。

分号在 Swift 里可省，这是刻意的现代设计。坚持一行一句就不写分号，代码最干净，也最符合社区风格。如果你从别的语言来，克制住加结尾分号的冲动，很快会习惯这种清爽。

import 是把能力请进文件的开关。纯语言学习阶段，多数例子连 Foundation 都不需要，标准库默认可用。等用到日期、文件等更丰富能力时，再 import 对应模块即可。别一上来就 import 一堆用不上的东西，那只会让文件变重、意图变模糊。

文件组织上，初学阶段一个 .swift 文件装下相关练习最省心。后面学模块和访问控制时，才会涉及跨文件如何组织。现在先把”顶层语句顺序执行”这个模型吃透，它是你理解程序从哪开始跑的关键。

还有一个小提醒：注释也能用来临时”关停”一段代码做对比实验。Swift 的多行注释还能嵌套，这点比 C 友好，当你想注释掉一大段本身含注释的代码时尤其方便。熟练用注释做实验，是低成本试错的好习惯。好的代码结构是”让人一眼看懂意图”。let/var 的选择、注释的密度、文件的划分，最终都服务于可读性。语法是骨架，结构是皮肉，两者都顺了，代码才真正好维护。

1-10 小结

Swift 文件的基本骨架是：可选的 import、顶层语句、各种定义。注释有单行 //、多行 /* */（还能嵌套）、文档 /// 三种。分号可省，一行一句时不写最地道。import 用来把 Foundation 等模块的能力请进文件。这些是所有 Swift 代码的通用底子，下一章起我们正式进入变量与常量的世界。