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 部分采用独立的、更细粒度的格式约定规则要求缩进每级 4 个空格禁止使用 Tab条件关键字与括号if与(之间必须有空格写作if (x)函数定义的大括号函数定义中{需另起新行零参数函数声明必须写作f(void)不得写f()else的放置}与else之间换行写作}换行else {禁止} else {if..else大括号一致性若链中任一分支使用{ }则全部分支都必须使用行尾空白同样禁止源码中的实际印证这些 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错误信息含义non-UNIX line endings行尾不是\n出现\rWindows 换行non-breaking space行内出现 U00A0 不换行空格tab使用了 Tab 字符受例外清单约束的文件除外no trailing newline文件末尾缺少换行符trailing whitespace行尾存在空白trailing blank lines文件末尾存在多余空行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、把 U00A0 替换为普通空格并在allow_tabs之外的路径上把行首 Tab 序列替换为 4 空格对齐见 check-whitespace.jl。注意脚本只在 Git 工作区中运行且--fix会修改文件内容提交前请用git diff复核改动。4. Tab 例外清单allow_tabs函数明确豁免了以下路径允许它们使用 Tab见 check-whitespace.jlMake.inc以及所有Makefile、*.make、*.mkMake 语法惯例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 titleWhitespace check,...的格式输出到 stdout使 GitHub Actions 在 PR 页面直接标注警告位置见 check-whitespace.jl。因此即使本地跳过检查CI 也会拦截不合规的空白问题。四、实践建议提交前的自查清单结合本文档与仓库工具提交 Julia 代码前可依次自查行宽单行不超过 92 字符含 docstring必要时合理断行空白无行尾空格、无 Tab除例外清单、无 U00A0、文件以换行符结尾字符集优先 ASCII 运算符与标识符术语docstring 中语言写作 Julia、可执行文件写作 juliaC 代码额外项4 空格缩进、if (x)空格、函数{换行、零参数用f(void)、else换行且大括号全链一致运行检查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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考