PRF:20190527 How to write a good C main function.md

@MjSeven

translated/tech/20190527 How to write a good C main function.md

@@ -12,11 +12,12 @@
 
 > 学习如何构造一个 C 文件并编写一个 C main 函数来成功地处理命令行参数。
 
-![Hand drawing out the word "code"][1]
+![Hand drawing out the word "code"](https://img.linux.net.cn/data/attachment/album/201906/08/211422umrzznnvmapcwuc3.jpg)
 
-我知道，现在孩子们用 Python 和 JavaScript 编写他们疯狂的“应用程序”。但是不要这么快就否定 C 语言 —— 它能够提供很多东西，并且简洁。如果你需要速度，用 C 语言编写可能就是你的答案。如果你正在寻找稳定的职业或者想学习如何捕获[空指针解引用][2]，C 语言也可能是你的答案！在本文中，我将解释如何构造一个 C 文件并编写一个 C main 函数来成功地处理命令行参数。
+我知道，现在孩子们用 Python 和 JavaScript 编写他们的疯狂“应用程序”。但是不要这么快就否定 C 语言 —— 它能够提供很多东西，并且简洁。如果你需要速度，用 C 语言编写可能就是你的答案。如果你正在寻找稳定的职业或者想学习如何捕获[空指针解引用][2]，C 语言也可能是你的答案！在本文中，我将解释如何构造一个 C 文件并编写一个 C main 函数来成功地处理命令行参数。
 
 我：一个顽固的 Unix 系统程序员。
+
 你：一个有编辑器、C 编译器，并有时间打发的人。
 
 让我们开工吧。
@@ -34,7 +35,7 @@ int main(int argc, char *argv[]) {
 }
 ```
 
-这个程序可以*编译*但不*执行*任何操作。
+这个程序可以*编译*但不*干*任何事。
 
 ```
 $ gcc main.c
@@ -46,7 +47,7 @@ $
 
 ### main 函数是唯一的。
 
-`main()` 函数是开始执行时所执行的程序的第一个函数，但不是第一个执行的函数。*第一个*函数是 `_start()`，它通常由 C 运行库提供，在编译程序时自动链接。此细节高度依赖于操作系统和编译器工具链，所以我假装没有提到它。
+`main()` 函数是开始执行时所执行的程序的第一个函数，但不是第一个执行的函数。*第一个*函数是 `_start()`，它通常由 C 运行库提供，在编译程序时自动链入。此细节高度依赖于操作系统和编译器工具链，所以我假装没有提到它。
 
 `main()` 函数有两个参数，通常称为 `argc` 和 `argv`，并返回一个有符号整数。大多数 Unix 环境都希望程序在成功时返回 `0`（零），失败时返回 `-1`（负一）。
 
@@ -55,13 +56,13 @@ $
 `argc` | 参数个数 | 参数向量的个数
 `argv` | 参数向量 | 字符指针数组
 
-参数向量 `argv` 是调用程序的命令行的标记化表示形式。在上面的例子中，`argv` 将是以下字符串的列表：
+参数向量 `argv` 是调用你的程序的命令行的标记化表示形式。在上面的例子中，`argv` 将是以下字符串的列表：
 
 ```
-`argv = [ "/path/to/a.out", "-o", "foo", "-vv" ];`
+argv = [ "/path/to/a.out", "-o", "foo", "-vv" ];
 ```
 
-参数向量保证在第一个索引中始终至少有一个字符串 `argv[0]`，这是执行程序的完整路径。
+参数向量在其第一个索引 `argv[0]` 中确保至少会有一个字符串，这是执行程序的完整路径。
 
 ### main.c 文件的剖析
 
@@ -86,24 +87,24 @@ int main(int argc, char *argv[]) {
 
 下面我将讨论这些编号的各个部分，除了编号为 0 的那部分。如果你必须把版权或许可文本放在源代码中，那就放在那里。
 
-另一件我不想谈论的事情是注释。
+另一件我不想讨论的事情是注释。
 
 ```
-"Comments lie."
-\- A cynical but smart and good looking programmer.
+“评论谎言。”
+- 一个愤世嫉俗但聪明又好看的程序员。
 ```
 
-使用有意义的函数名和变量名，而不是注释。
+与其使用注释，不如使用有意义的函数名和变量名。
 
-为了迎合程序员固有的惰性，一旦添加了注释，维护负荷就会增加一倍。如果更改或重构代码，则需要更新或扩展注释。随着时间的推移，代码会发生变化，与注释所描述的内容完全不同。
+鉴于程序员固有的惰性，一旦添加了注释，维护负担就会增加一倍。如果更改或重构代码，则需要更新或扩充注释。随着时间的推移，代码会变得面目全非，与注释所描述的内容完全不同。
 
-如果你必须写注释，不要写关于代码正在做*什么*，相反，写下*为什么*代码需要这样写。写一些你想在五年后读到的注释，那时你已经将这段代码忘得一干二净。世界的命运取决于你。*不要有压力。*
+如果你必须写注释，不要写关于代码正在做*什么*，相反，写下代码*为什么*要这样写。写一些你将要在五年后读到的注释，那时你已经将这段代码忘得一干二净。世界的命运取决于你。*不要有压力。*
 
-#### 1、 包含
+#### 1、包含
 
-我添加到 `main.c` 文件的第一个东西是包含文件，它们为程序提供大量标准 C 标准库函数和变量。C 标准库做了很多事情。浏览 `/usr/include` 中的头文件，了解它们可以为你做些什么。
+我添加到 `main.c` 文件的第一个东西是包含文件，它们为程序提供大量标准 C 标准库函数和变量。C 标准库做了很多事情。浏览 `/usr/include` 中的头文件，你可以了解到它们可以做些什么。
 
-`#include` 字符串是 [C 预处理程序][4]（cpp）指令，它会将引用的文件完整地包含在当前文件中。C 中的头文件通常以 `.h` 扩展名命名，且不应包含任何可执行代码。它只有宏、定义、类型定义、外部变量和函数原型。字符串 `<header.h>` 告诉 cpp 在系统定义的头文件路径中查找名为 `header.h` 的文件，通常在 `/usr/include` 目录中。
+`#include` 字符串是 [C 预处理程序][4]（cpp）指令，它会将引用的文件完整地包含在当前文件中。C 中的头文件通常以 `.h` 扩展名命名，且不应包含任何可执行代码。它只有宏、定义、类型定义、外部变量和函数原型。字符串 `<header.h>` 告诉 cpp 在系统定义的头文件路径中查找名为 `header.h` 的文件，它通常在 `/usr/include` 目录中。
 
 ```
 /* main.c */
@@ -117,17 +118,17 @@ int main(int argc, char *argv[]) {
 #include <sys/types.h>
 ```
 
-以上内容是我默认会包含的最小全局包含集合：
+这是我默认会全局包含的最小包含集合，它将引入：
 
 \#include 文件 | 提供的东西
 ---|---
-stdio | 提供 FILE、stdin、stdout、stderr 和 `fprint()` 函数系列
+stdio | 提供 `FILE`、`stdin`、`stdout`、`stderr` 和 `fprint()` 函数系列
 stdlib | 提供 `malloc()`、`calloc()` 和 `realloc()`
 unistd | 提供 `EXIT_FAILURE`、`EXIT_SUCCESS`
 libgen | 提供 `basename()` 函数
-errno | 定义外部 errno 变量及其可以接受的所有值
+errno | 定义外部 `errno` 变量及其可以接受的所有值
 string | 提供 `memcpy()`、`memset()` 和 `strlen()` 函数系列
-getopt | 提供外部 optarg、opterr、optind 和 `getopt()` 函数
+getopt | 提供外部 `optarg`、`opterr`、`optind` 和 `getopt()` 函数
 sys/types | 类型定义快捷方式，如 `uint32_t` 和 `uint64_t`
 
 #### 2、定义
@@ -144,11 +145,11 @@ sys/types | 类型定义快捷方式，如 `uint32_t` 和 `uint64_t`
 #define DEFAULT_PROGNAME "george"
 ```
 
-这在现在没有多大意义，但 `OPTSTR` 定义我会说明一下，它是程序推荐的命令行开关。参考 [getopt(3)][5] man 页面，了解 `OPTSTR` 将如何影响 `getopt()` 的行为。
+这在现在没有多大意义，但 `OPTSTR` 定义我这里会说明一下，它是程序推荐的命令行开关。参考 [getopt(3)][5] man 页面，了解 `OPTSTR` 将如何影响 `getopt()` 的行为。
 
-`USAGE_FMT` 定义了一个 `printf()` 风格形式的格式字符串，在 `usage()` 函数中被引用。
+`USAGE_FMT` 定义了一个 `printf()` 风格的格式字符串，它用在 `usage()` 函数中。
 
-我还喜欢将字符串常量放在文件的这一部分作为 `#defines`。如果需要，把它们收集在一起可以更容易地修复拼写、重用消息和国际化消息。
+我还喜欢将字符串常量放在文件的 `#define` 这一部分。如果需要，把它们收集在一起可以更容易地修正拼写、重用消息和国际化消息。
 
 最后，在命名 `#define` 时全部使用大写字母，以区别变量和函数名。如果需要，可以将单词放连在一起或使用下划线分隔，只要确保它们都是大写的就行。
 
@@ -163,7 +164,7 @@ extern char *optarg;
 extern int opterr, optind;
 ```
 
-`extern` 声明将该名称带入当前编译单元的命名空间（也称为 “文件”），并允许程序访问该变量。这里我们引入了三个整数变量和一个字符指针的定义。`opt` 前缀的几个变量是由 `getopt()` 函数使用的，C 标准库使用 `errno` 作为带外通信通道来传达函数可能的失败原因。
+`extern` 声明将该名称带入当前编译单元的命名空间（即 “文件”），并允许程序访问该变量。这里我们引入了三个整数变量和一个字符指针的定义。`opt` 前缀的几个变量是由 `getopt()` 函数使用的，C 标准库使用 `errno` 作为带外通信通道来传达函数可能的失败原因。
 
 #### 4、类型定义
 
@@ -179,7 +180,7 @@ typedef struct {
 } options_t;
 ```
 
-在外部声明之后，我喜欢为结构、联合和枚举声明 `typedef`。命名一个 `typedef` 本身就是一种传统行为。我非常喜欢使用 `_t` 后缀来表示该名称是一种类型。在这个例子中，我将 `options_t` 声明为一个包含 4 个成员的 `struct`。C 是一种空格无关的编程语言，因此我使用空格将字段名排列在同一列中。我只是喜欢它看起来的样子。对于指针声明，我在名称前面加上星号，以明确它是一个指针。
+在外部声明之后，我喜欢为结构、联合和枚举声明 `typedef`。命名一个 `typedef` 是一种传统习惯。我非常喜欢使用 `_t` 后缀来表示该名称是一种类型。在这个例子中，我将 `options_t` 声明为一个包含 4 个成员的 `struct`。C 是一种空格无关的编程语言，因此我使用空格将字段名排列在同一列中。我只是喜欢它看起来的样子。对于指针声明，我在名称前面加上星号，以明确它是一个指针。
 
 #### 5、全局变量声明
 
@@ -190,7 +191,7 @@ typedef struct {
 int dumb_global_variable = -11;
 ```
 
-全局变量是一个坏主意，你永远不应该使用它们。但如果你必须使用全局变量，请在这里声明并确保给它们一个默认值。说真的，*不要使用全局变量*。
+全局变量是一个坏主意，你永远不应该使用它们。但如果你必须使用全局变量，请在这里声明，并确保给它们一个默认值。说真的，*不要使用全局变量*。
 
 #### 6、函数原型
 
@@ -202,7 +203,7 @@ void usage(char *progname, int opt);
 int do_the_needful(options_t *options);
 ```
 
-在编写函数时，将它们添加到 `main()` 函数之后而不是之前，在这里放函数原型。早期的 C 编译器使用单遍策略，这意味着你在程序中使用的每个符号（变量或函数名称）必须在使用之前声明。现代编译器几乎都是多遍编译器，它们在生成代码之前构建一个完整的符号表，因此并不严格要求使用函数原型。但是，有时你无法选择代码要使用的编译器，所以请编写函数原型并继续。
+在编写函数时，将它们添加到 `main()` 函数之后而不是之前，在这里放函数原型。早期的 C 编译器使用单遍策略，这意味着你在程序中使用的每个符号（变量或函数名称）必须在使用之前声明。现代编译器几乎都是多遍编译器，它们在生成代码之前构建一个完整的符号表，因此并不严格要求使用函数原型。但是，有时你无法选择代码要使用的编译器，所以请编写函数原型并继续这样做下去。
 
 当然，我总是包含一个 `usage()` 函数，当 `main()` 函数不理解你从命令行传入的内容时，它会调用这个函数。
 
@@ -261,20 +262,20 @@ int main(int argc, char *argv[]) {
 }
 ```
 
-好吧，代码有点多。`main()` 函数的目的是收集用户提供的参数，执行最基本的输入验证，然后将收集到的参数传递给使用它们的函数。这个示例声明一个使用默认值初始化的 `options` 变量，并解析命令行，根据需要更新 `options`。
+好吧，代码有点多。这个 `main()` 函数的目的是收集用户提供的参数，执行最基本的输入验证，然后将收集到的参数传递给使用它们的函数。这个示例声明一个使用默认值初始化的 `options` 变量，并解析命令行，根据需要更新 `options`。
 
-`main()` 函数的核心是一个 `while` 循环，它使用 `getopt()` 来遍历 `argv`，寻找命令行选项及其参数（如果有的话）。文件前面的 `OPTSTR` 定义是驱动 `getopt()` 行为的模板。`opt` 变量接受 `getopt()` 找到的任何命令行选项的字符值，程序对检测命令行选项的响应发生在 `switch` 语句中。
+`main()` 函数的核心是一个 `while` 循环，它使用 `getopt()` 来遍历 `argv`，寻找命令行选项及其参数（如果有的话）。文件前面定义的 `OPTSTR` 是驱动 `getopt()` 行为的模板。`opt` 变量接受 `getopt()` 找到的任何命令行选项的字符值，程序对检测命令行选项的响应发生在 `switch` 语句中。
 
-现在你注意到了可能会问，为什么 `opt` 被声明为 32 位 `int`，但是预期是 8 位 `char`？事实上 `getopt()` 返回一个 `int`，当它到达 `argv` 末尾时取负值，我会使用 `EOF`（*文件末尾*标记）匹配。`char` 是有符号的，但我喜欢将变量匹配到它们的函数返回值。
+如果你注意到了可能会问，为什么 `opt` 被声明为 32 位 `int`，但是预期是 8 位 `char`？事实上 `getopt()` 返回一个 `int`，当它到达 `argv` 末尾时取负值，我会使用 `EOF`（*文件末尾*标记）匹配。`char` 是有符号的，但我喜欢将变量匹配到它们的函数返回值。
 
-当检测到一个已知的命令行选项时，会发生特定的行为。有些选项有一个参数，在 `OPTSTR` 中指定了一个以冒号结尾的参数。当一个选项有一个参数时，`argv` 中的下一个字符串可以通过外部定义的变量 `optarg` 提供给程序。我使用 `optarg` 打开文件进行读写，或者将命令行参数从字符串转换为整数值。
+当检测到一个已知的命令行选项时，会发生特定的行为。在 `OPTSTR` 中指定一个以冒号结尾的参数，这些选项可以有一个参数。当一个选项有一个参数时，`argv` 中的下一个字符串可以通过外部定义的变量 `optarg` 提供给程序。我使用 `optarg` 来打开文件进行读写，或者将命令行参数从字符串转换为整数值。
 
-这里有几个关于风格的要点：
+这里有几个关于代码风格的要点：
 
-  * 将 `opterr` 初始化为 0，禁止 `getopt` 发出 `?`。
+  * 将 `opterr` 初始化为 `0`，禁止 `getopt` 触发 `?`。
   * 在 `main()` 的中间使用 `exit(EXIT_FAILURE);` 或 `exit(EXIT_SUCCESS);`。
   * `/* NOTREACHED */` 是我喜欢的一个 lint 指令。
-  * 在函数末尾使用 `return EXIT_SUCCESS;` 返回一个 int 类型。
+  * 在返回 int 类型的函数末尾使用 `return EXIT_SUCCESS;`。
   * 显示强制转换隐式类型。
 
 这个程序的命令行格式，经过编译如下所示：
@@ -316,25 +317,25 @@ int do_the_needful(options_t *options) {
 }
 ```
 
-最后，我编写的函数不是样板函数。在本例中，函数 `do_the_needful()` 接受指向 `options_t` 结构的指针。我验证 `options` 指针不为 `NULL`，然后继续验证 `input` 和 `output` 结构成员。如果其中一个测试失败，返回 `EXIT_FAILURE`，并且通过将外部全局变量 `errno` 设置为常规错误代码，我向调用者发出一个原因的信号。调用者可以使用便捷函数 `perror()` 来根据 `errno` 的值发出人类可读的错误消息。
+我最后编写的函数不是个样板函数。在本例中，函数 `do_the_needful()` 接受一个指向 `options_t` 结构的指针。我验证 `options` 指针不为 `NULL`，然后继续验证 `input` 和 `output` 结构成员。如果其中一个测试失败，返回 `EXIT_FAILURE`，并且通过将外部全局变量 `errno` 设置为常规错误代码，我可以告知调用者常规的错误原因。调用者可以使用便捷函数 `perror()` 来根据 `errno` 的值发出便于阅读的错误消息。
 
-函数几乎总是以某种方式验证它们的输入。如果完全验证代价很大，那么尝试执行一次并将验证后的数据视为不可变。`usage()` 函数使用 `fprintf()` 调用中的条件赋值验证 `progname` 参数。`usage()` 函数无论如何都要退出，所以我不需要设置 `errno` 或为使用正确的程序名大吵一场。
+函数几乎总是以某种方式验证它们的输入。如果完全验证代价很大，那么尝试执行一次并将验证后的数据视为不可变。`usage()` 函数使用 `fprintf()` 调用中的条件赋值验证 `progname` 参数。接下来 `usage()` 函数就退出了，所以我不会费心设置 `errno`，也不用操心是否使用正确的程序名。
 
-在这里，我要避免的最大错误是解引用 `NULL` 指针。这将导致操作系统向我的进程发送一个名为 `SYSSEGV` 的特殊信号，导致不可避免的死亡。用户希望看到的是由 `SYSSEGV` 引起的崩溃。为了发出更好的错误消息并优雅地关闭程序，捕获 `NULL` 指针要好得多。 
+在这里，我要避免的最大错误是解引用 `NULL` 指针。这将导致操作系统向我的进程发送一个名为 `SYSSEGV` 的特殊信号，导致不可避免的死亡。用户最不希望看到的是由 `SYSSEGV` 而导致的崩溃。最好是捕获 `NULL` 指针以发出更合适的错误消息并优雅地关闭程序。 
 
-有些人抱怨在函数体中有多个 `return` 语句，他们争论“控制流的连续性”和其他东西。老实说，如果函数中间出现错误，那么这个时候是返回错误条件的好时机。写一大堆嵌套的 `if` 语句只有一个 `return` 绝不是一个“好主意”™。
+有些人抱怨在函数体中有多个 `return` 语句，他们喋喋不休地说些“控制流的连续性”之类的东西。老实说，如果函数中间出现错误，那就应该返回这个错误条件。写一大堆嵌套的 `if` 语句只有一个 `return` 绝不是一个“好主意”™。
 
-最后，如果你编写的函数接受四个或更多参数，请考虑将它们绑定到一个结构中，并传递一个指向该结构的指针。这使得函数签名更简单，更容易记住，并且在以后调用时不会出错。它还使调用函数速度稍微快一些，因为需要复制到函数堆栈中的东西更少。在实践中，只有在函数被调用数百万或数十亿次时，才会考虑这个问题。如果认为这没有意义，那么不要担心。
+最后，如果你编写的函数接受四个以上的参数，请考虑将它们绑定到一个结构中，并传递一个指向该结构的指针。这使得函数签名更简单，更容易记住，并且在以后调用时不会出错。它还可以使调用函数速度稍微快一些，因为需要复制到函数堆栈中的东西更少。在实践中，只有在函数被调用数百万或数十亿次时，才会考虑这个问题。如果认为这没有意义，那也无所谓。
 
-### 等等，你说没有注释 !?!!
+### 等等，你不是说没有注释吗！？！！
 
-在 `do_the_needful()` 函数中，我写了一种特殊类型的注释，它被设计为占位符而不是说明代码：
+在 `do_the_needful()` 函数中，我写了一种特殊类型的注释，它被是作为占位符设计的，而不是为了说明代码：
 
 ```
-`/* XXX do needful stuff */`
+/* XXX do needful stuff */
 ```
 
-当你在该区域时，有时你不想停下来编写一些特别复杂的代码，你会之后再写，而不是现在。那就是我留给自己再次回来的地方。我插入一个带有 `XXX` 前缀的注释和一个描述需要做什么的简短注释。之后，当我有更多时间的时候，我会在源代码中寻找 `XXX`。使用什么并不重要，只要确保它不太可能在另一个上下文中以函数名或变量形式显示在代码库中。
+当你写到这里时，有时你不想停下来编写一些特别复杂的代码，你会之后再写，而不是现在。那就是我留给自己再次回来的地方。我插入一个带有 `XXX` 前缀的注释和一个描述需要做什么的简短注释。之后，当我有更多时间的时候，我会在源代码中寻找 `XXX`。使用什么前缀并不重要，只要确保它不太可能在另一个上下文环境（如函数名或变量）中出现在你代码库里。
 
 ### 把它们组合在一起