企业官网建设流程全解析

Julia 仓库代码格式规范：风格指南、92 字符行宽与自动化空白检查

【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/julia

本指南以 Julia 官方仓库的开发文档 doc/src/devdocs/contributing/formatting.md 为主体，系统梳理 Julia 语言本身与 C 运行时（runtime）两套代码的格式化约定，并结合仓库内的 风格指南、文档编写规范 与 check-whitespace.jl 自动化检查脚本，帮助贡献者写出风格统一、易于审查与维护的代码。读完本文，你将掌握 Julia 与 C 贡献代码的每条格式细则、行宽与空白的判定标准，以及如何用仓库自带脚本自查并自动修复空白问题。

一、Julia 代码的通用格式指南

仓库对 Julia 代码贡献者提出了六条核心格式要求，涵盖风格基准、可读性、行宽、字符集与术语规范。

1. 以最新开发版风格指南为基准

贡献的 Julia 代码应始终跟随仓库开发分支所对应的 Julia Style Guide。该文档位于doc/src/manual/style-guide.md，包含约 20 个主题章节，例如：

• 使用 4 个空格作为每级缩进（Use 4 spaces per indentation level，见 style-guide.md）；
• 编写函数而非脚本、编写 docstring、避免过度具体的类型；
• 为修改参数的函数名追加!、避免类型盗用（type piracy）等约定。

评审 PR 时，任何与风格指南冲突的新代码都会被要求修正，因此提交前先通读该文档是基本功课。

2. 用空白提升可读性，禁止行尾空白

• 善用空白：在运算符、逗号、赋值号两侧留出空格，用空行分隔逻辑块，让代码的"呼吸感"服务于可读性；
• 禁止尾随空白（trailing whitespace）：每一行末尾不得出现多余的空格或 Tab。这条规则同时出现在 Julia 与 C 两部分指南中，是仓库强制的硬性检查项（详见后文自动化检查）。

3. 尽量遵守 92 字符行宽限制

Julia 代码建议将每行长度控制在92 个字符以内。这一限制不只针对普通代码：

• 文档字符串（docstring）同样适用。在 doc/src/manual/documentation.md 的"Docstrings"一节明确写道："Docstrings 与代码使用相同的工具编辑，因此应遵循相同约定，建议每行不超过 92 字符"；
• 92 字符是"建议"而非绝对禁令，但对于必须换行的场景，应选择合理的断行位置，保持缩进对齐与可读性。

4. 优先使用 ASCII 运算符与标识符

在可行的情况下，尽量使用 ASCII 运算符和标识符，而非 Unicode 等价物。例如优先使用x -> x^2、a <= b，而不是x → x²、a ≤ b等写法（除非该写法是领域惯例且显著提升可读性）。这一约定降低了跨编辑器、跨平台、跨编码环境的协作成本，也让代码在终端与 diff 工具中更容易处理。

5. 文档字符串中的术语规范

在 docstring 中称呼语言时统一用"Julia"，称呼可执行程序时统一用"julia"（等宽字体）。例如："juliais the Julia executable" 而不是 "Julia is the executable" 之类的混用，避免用户混淆"语言"与"命令行工具"两个概念。

二、C 代码的通用格式指南

Julia 的运行时与编译器有大量 C/C++ 代码（位于 src 目录，如src/gc-common.c、src/support/等）。C 部分采用独立的、更细粒度的格式约定：

源码中的实际印证

这些 C 约定在仓库源码中有大量实例可对照：

• f(void)零参数声明：在 src/support/libsupportinit.c 中写作void libsupport_init(void)，对应头文件声明 src/support/libsupportinit.c 的同名声明 也统一为void ios_init_stdstreams(void)；
• if (x)空格约定：遍览 src/gc-common.c 等文件，所有if、while、for关键字与括号之间均保留空格；
• 函数{另起一行：例如 src/builtins.c 中void jl_init_intrinsic_properties(void)后的大括号位于独立行。

之所以强调f(void)而非f()，是因为在 C 标准中f()表示"参数未指定"（旧式风格），而f(void)才明确表示"零参数"，语义更严谨、可移植性更好。

三、自动化检查：check-whitespace.jl

格式约定并非只靠人工自觉，仓库提供了可执行的检查脚本 contrib/check-whitespace.jl，用于在本地与 CI 中统一校验空白规范。

1. 检查范围

脚本默认通过git ls-files获取仓库跟踪的全部代码文件，文件类型模式包括：*.c、*.cpp、*.h、*.inc、*.jl、*.lsp、*.scm、*.sh、*.yml、*.mk、*.rst、*.md、Makefile等（见 check-whitespace.jl）。

2. 检查项清单

脚本对每个文件逐行扫描，报告以下问题（见 check-whitespace.jl）：

3. 使用方法

在仓库根目录执行：

# 仅检查，输出所有问题并给出退出码（0=通过，1=存在错误） julia contrib/check-whitespace.jl # 自动修复：去除行尾空白、规范化换行、替换不换行空格， # 并在允许的范围内把行首 Tab 序列替换为等宽空格 julia contrib/check-whitespace.jl --fix # 通过 stdin 传入待检查文件列表 git diff --name-only | julia contrib/check-whitespace.jl --stdin

--fix模式会直接改写文件：将每行行尾空白与换行符规范化为\n、把 U+00A0 替换为普通空格，并在allow_tabs之外的路径上把行首 Tab 序列替换为 4 空格对齐（见 check-whitespace.jl）。注意：脚本只在 Git 工作区中运行，且--fix会修改文件内容，提交前请用git diff复核改动。

4. Tab 例外清单

allow_tabs函数明确豁免了以下路径，允许它们使用 Tab（见 check-whitespace.jl）：

• Make.inc以及所有Makefile、*.make、*.mk（Make 语法惯例）；
• src/support/与src/flisp/目录（从 Scheme/既有 C 代码库继承的历史风格）；
• test/syntax.jl与test/triplequote.jl（这两个测试文件本身以字符串字面量形式测试 Tab 相关语法，见 test/syntax.jl 与 test/triplequote.jl）。

除此之外的所有 C/Julia 代码文件，出现 Tab 即报错——这与"Julia 用 4 空格缩进、C 用 4 空格且禁 Tab"的格式指南完全对应。

5. CI 集成

脚本支持 GitHub Actions 环境变量GITHUB_ACTIONS：当在 CI 中运行时，每个问题会额外以::warning title=Whitespace check,...的格式输出到 stdout，使 GitHub Actions 在 PR 页面直接标注警告位置（见 check-whitespace.jl）。因此即使本地跳过检查，CI 也会拦截不合规的空白问题。

四、实践建议：提交前的自查清单

结合本文档与仓库工具，提交 Julia 代码前可依次自查：

1. 行宽：单行不超过 92 字符（含 docstring），必要时合理断行；
2. 空白：无行尾空格、无 Tab（除例外清单）、无 U+00A0、文件以换行符结尾；
3. 字符集：优先 ASCII 运算符与标识符；
4. 术语：docstring 中语言写作 "Julia"、可执行文件写作 "julia"；
5. C 代码额外项：4 空格缩进、if (x)空格、函数{换行、零参数用f(void)、else换行且大括号全链一致；
6. 运行检查：julia contrib/check-whitespace.jl确认输出Whitespace check found no issues.后再提交。

五、总结

格式规范的价值在于让海量贡献者协作时保持代码的一致性与可读性：Julia 侧以 92 字符行宽、4 空格缩进、ASCII 优先与术语规范为核心；C 侧则叠加了更严格的if (x)空格、f(void)零参数声明、大括号换行与全链一致等约定。这些规则不仅写在 formatting.md 中，更有 check-whitespace.jl 在本地与 CI 双端把关。对希望向 Julia 提交代码的开发者而言，遵循本文档并跑通空白检查，是进入评审流程前最基本也最稳妥的一步。

【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/julia