diff --git a/doc/03-为什么拒绝使用代码格式化工具.md b/doc/03-为什么拒绝使用代码格式化工具.md index f9487bf..c781a98 100644 --- a/doc/03-为什么拒绝使用代码格式化工具.md +++ b/doc/03-为什么拒绝使用代码格式化工具.md @@ -6,7 +6,7 @@ ! Doc Authors : Aoran Zeng ! Contributors : Nul None ! Created On : <2025-08-10> - ! Last Modified : <2025-08-11> + ! Last Modified : <2025-08-17> ! ---------------------------------------------------------- --> # chsrc 代码风格 @@ -19,16 +19,22 @@ Ruby 的语法优美性在编程行业中具有标杆地位。Matz(松本行
+ + ## 为什么我们坚持不使用代码格式化工具 代码格式化工具(code formatter)在多人协作的代码仓库中确实有其价值,**参与的人越多,统一格式的需求越迫切**。然而,`chsrc` 项目经过深思熟虑后,拒绝使用代码格式化工具。让我来说明这一决定背后的深层原因。 -像 `Prettier` 这样的工具表面上带来了统一性,但其代价是什么?**它是极度专制的(opiniated)**,这意味着为了获得表面的一致性,我们必须**完全交出代码审美的自主权**。今天我们大部分人使用 `Prettier`,**并非出于真心的认同,而是因为整个前端生态圈的集体胁迫——不用就意味着被边缘化**。 +像 `Prettier` 这样的工具表面上带来了统一性,但其代价是什么?**它是极度专制的(opiniated)**,这意味着为了获得表面的一致性,我们必须**完全交出代码审美的自主权**。今天我们大部分人使用 `Prettier`,**并非出于真心的认同,而是因为整个前端生态圈的集体胁迫——不用就意味着被边缘化**。每一个有追求的程序员都应该保留**对代码美学的最后决定权,格式化工具的便利性不应该以牺牲美观性和可维护性为代价**。 这种现象的本质令人深思:**少数 `Prettier` 维护者的个人偏好,竟然决定了全球数百万开发者的代码美学标准。这显然是一种技术独裁,坚决拒绝向格式化工具的霸权低头**。 C语言的格式化工具通常选择 `clang-format`,它的配置选项十分丰富,比 `Prettier` 要理性得多。然而,即便如此,**其配置的复杂性和局限性仍然无法满足 chsrc 对代码美学的严苛要求**。如果你是一位 `clang-format` 的配置专家,我们诚挚邀请您告诉我们如何优雅地处理以下代码场景,**也许这能改变我的立场**。 +
+ + + ### 挑战案例 以下是我认为自动格式化工具很难完美处理的代码场景: @@ -64,15 +70,7 @@ if (!matched) matched = iterate_menu (chsrc_wr_menu, input, &target_tmp);
-## 我们的立场 -**代码不仅仅是给机器执行的指令,更是团队协作和项目传承的重要载体**。 - -每一个有追求的程序员都应该保留对代码美学的最后决定权。格式化工具的便利性不应该以牺牲创造力和个性为代价。在 `chsrc` 项目中,我们选择用更多的时间和精力来精心设计每一行代码。正如 Ruby 社区所倡导的那样,**程序员的幸福感不应该被自动化工具的专制所剥夺。我们追求的不是表面的一致性,而是深层次的代码质量和表达力。这不是对工具的盲目排斥,而是对程序员自主性的坚持。这不是标新立异的固执,而是对代码质量的不妥协。** - -如果你也认同 **代码应该为人类而写** 的理念,欢迎加入我们,一起创造真正优质的代码。 - -
## C语言代码风格 @@ -80,15 +78,37 @@ if (!matched) matched = iterate_menu (chsrc_wr_menu, input, &target_tmp); - 类型名: `PascalCase_t` -- 函数调用时,函数名和`()`之间应当保持一个空格。但是当函数参数为0或1时,不保持该空格 - - 函数定义时,函数名和`()`之间始终保持一个空格 +- 函数和函数定义之间保持**2个空行**,若一系列函数和一系列函数存在主题性区别,**可用3个空行** + +- 函数调用时,函数名和`()`之间应当保持一个空格 + + 例外: 当函数参数为0或1时不用保持该空格。 + + 但若该函数参数过长如很长的字符串,又或嵌套了函数,我们仍然保持一个空格。 + +```c +// 一般函数调用都空格,因为这是 GNU 风格最显著的特征之一 +func (1, 2); + +// 这两种情况不用保持空格,因为没有必要 +br(); +red("string"); + +// 但如果有函数嵌套,即使参数只有1个,外部函数还是要保持空格,这样清晰地多 +func1 (func2("string")); +// 如果参数过长,即使参数只有1个,也应该保持空格 +red ("loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong string"); +``` +
+ + ## 其他语言代码风格 -我们秉承 **入乡随俗、尊重传统** 的原则,尊重每种语言社区的既定传统。比如,`YAML` 使用2个空格的优雅,`JSON`使用4个空格的规整,`Perl` 使用 Larry Wall 钟爱的4个空格传统。 +我们秉承 **入乡随俗、尊重传统** 的原则,尊重每种语言社区的既定传统。比如,`YAML` 使用2个空格,`JSON`使用4个空格,`Perl` 使用 Larry Wall 钟爱的4个空格。 我们使用 `.editorconfig` 来确保这些格式的应用。