图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载本文以 MuPDF 官方编码风格文档为骨架系统梳理其 C 库fitz公共层与pdf/xps等解释器层在缩进、命名、基础类型假设与引用计数上的硬性约定并结合仓库源码如 source/fitz/document.c、source/fitz/bitmap.c、source/fitz/context.c印证这些规则在实际实现中的落地方式。读完本文你将能够快速读懂 MuPDF 源码的命名语义、准确判断一个函数返回值是否归你所有以及为 MuPDF 贡献代码时写出风格一致的补丁。缩进两条不可妥协的硬规则MuPDF 的缩进风格非常简洁其全部精髓浓缩为两条硬性规则详见 docs/reference/c/coding-style.md必须使用硬制表符hard tab缩进禁止在左边界之外做任何形式的垂直对齐Do not vertically align anything beyond the left edge。这意味着你不需要也不应该手动把赋值号、注释符//之类的元素在列方向上对齐也不需要在行首使用空格。如果你偏好不同的视觉宽度只需在自己的编辑器中配置自己喜欢的 tab 宽度如 4 或 8 空格宽度只要遵循上述两条规则任何人的代码在你的编辑器里都会整齐一致——这正是tab 缩进 不做列对齐的协作价值样式冲突被彻底消除。其余细节可以通过观察既有源码自然习得大括号独占一行Allman 风格例如void fz_drop_document(fz_context *ctx, fz_document *doc) { if (fz_drop_imp(ctx, doc, doc-refs)) { ... } }if、for、while与其表达式之间留一个空格例如if (cond)而非if(cond)。从 source/fitz/document.c 的实现可以看到上述两条规则在真实的 MuPDF 代码中被严格执行函数返回类型与函数名分行书写左花括号独占一行关键字与括号间有空格。命名动词驱动的函数命名体系MuPDF 的函数命名遵循一套固定的短语模式这让读者仅凭函数名就能推断其行为模式语义示例verb_noun动作 对象fz_drop_document、fz_keep_bitmapverb_noun_with_noun动作 对象 介词对象fz_new_document_of_sizenoun_attribute名词 属性读取属性fz_document_supports_acceleratorset_noun_attribute设置属性fz_tune_image_scalenoun_from_noun类型转换避免noun_to_nounfz_new_bitmap_from_pixmap其中verb_noun模式在源码中随处可见例如 source/fitz/bitmap.c 中的fz_keep_bitmap/fz_drop_bitmap成对出现构成典型的生命周期管理接口。前缀约定导出的符号必须带前缀对于导出的函数、宏、枚举、全局变量和类型前缀是强制性的fz—— 用于公共通用代码fitz层如fz_context、fz_documentpdf、xps等—— 用于各解释器特有代码如pdf_obj、xps_document。对于私有函数和类型前缀是可选的但鼓励使用。在 MuPDF 源码中大量内部辅助函数会写成static并省略前缀例如 source/fitz/context.c 中的fz_new_tuning_context、fz_keep_tuning_context虽然是static私有函数但仍保留了fz_前缀。避免无意义的 get文档明确要求避免使用get作为函数名的一部分因为它是一个无意义、冗余的填充词。例如读取文档元数据用的是fz_lookup_metadata见 include/mupdf/fitz/document.h而不是fz_get_metadata。保留词引用计数的语义标记有一组词被保留用于表达引用计数语义这是 MuPDF 命名体系中最关键的部分new、create、find、load、open、keep—— 返回一个你负责释放的对象drop—— 放弃对传入对象的所有权即减少一次引用并可能释放。当需要查找一个对象或值时选择哪个词取决于返回值是否转移所有权lookup—— 返回值或借用指针borrowed pointer调用方不负责释放find—— 返回一个调用方负责释放的对象。例如 include/mupdf/fitz/document.h 中打开文档的 API 命名为fz_open_document返回fz_document *调用方随后必须fz_drop_document而查询书签的接口则是fz_lookup_bookmark借用式查询。类型贯穿全库的位宽假设MuPDF 对 C 基础整数类型做了明确且统一的假设编写或阅读代码时必须遵守类型约定int至少 32 位short恰好 16 位char恰好 8 位size_t用于数组大小、字符串长度与内存分配计量32 位构建下为 32 位所有 64 位构建下为 64 位unsigned char/uint8_t用于数据缓冲区byte bufferint64_t用于文件/流内的偏移量offset此外浮点运算优先使用float而非double在能够满足精度需求的前提下并假设其符合 IEEE 规范。这些约定与源码实现完全一致例如 source/fitz/bitmap.c 的fz_new_bitmap接收int w, int h描述像素尺寸而以size_t计算h * stride的内存分配见 source/fitz/bitmap.csource/fitz/buffer.c 的fz_new_buffer(fz_context *ctx, size_t size)也以size_t表达缓冲区大小。流内偏移相关接口在fz_stream体系中使用 64 位有符号整数以支持超大文件。引用计数所有权转移的完整规则MuPDF 的所有核心对象fz_context、fz_document、fz_bitmap、fz_pixmap、fz_buffer等都通过引用计数管理生命周期而所有权规则完全由函数名中的保留词表达。取走所有权的词new / find / load / open / keep若一个函数名包含上述任一保留词则其返回的对象归你所有你必须在使用完毕后调用drop、free或close来释放否则会造成泄漏。你只能通过以保留词命名的函数来转移这份所有权——即你不能在一个名为fz_some_utility的普通函数里返回一个你持有的对象并指望调用方去释放。源码佐证在 source/fitz/document.c 中fz_new_document_of_size创建对象后立即doc-refs 1把初始引用计数置为 1表示这份所有权已交付给调用方。对应的fz_keep_documentsource/fitz/document.c通过fz_keep_imp(ctx, doc, doc-refs)递增引用计数而fz_drop_documentsource/fitz/document.c通过fz_drop_imp递减并在归零后执行真正的清理释放用户 CSS、调用drop_document回调、释放结构体本身。同样的模式出现在 source/fitz/bitmap.cfz_keep_bitmap递增refsfz_drop_bitmap在计数归零后释放samples与结构体。释放所有权的词dropdrop表示放弃传入对象的所有权——即减少一次引用当引用计数归零时对象会被真正销毁。注意与释放内存的细微差别drop的是所有权引用对象是否真正释放取决于计数。借用对象没有保留词的函数返回值任何由不包含保留词命名的函数返回的对象都是借用的borrowed生命周期有限。你不能将其保存超过当前函数的执行时长也不能把它塞进结构体中长期持有。如果确实需要长期使用你有两个选择调用对应的keep函数如fz_keep_document、fz_keep_bitmap将其升级为你自己的引用自行制作一份拷贝。这一点在 source/fitz/context.c 的fz_drop_context中同样体现整个 MuPDF 上下文对象本身就是一个大型引用计数对象fz_new_context内部实现为fz_new_context_imp见 source/fitz/context.c创建时引用计数为 1多线程场景下子上下文通过keep/drop维护计数直到最后一个引用释放时才会执行字体缓存、存储store、字形缓存等一系列终结清理见 source/fitz/context.c。错误处理中的所有权值得注意的还有 MuPDF 独特的错误处理范式在fz_always/fz_catch块中正确释放对象。例如 source/fitz/context.c 中读取用户 CSS 文件的逻辑无论成功与否都会在fz_always块中fz_drop_buffer(ctx, buf)确保异常路径下也不泄漏——这是引用计数规则与 MuPDF 异常模型fz_try/fz_catch/fz_always配合使用的标准写法。实战自查清单在阅读或提交 MuPDF 代码时可以用下面这份清单快速校验风格合规性缩进使用硬 tab且未做任何超出左边界的列对齐大括号独占一行if/for/while后带空格导出符号带有fz_、pdf_、xps_等强制前缀函数名符合verb_noun等命名模式且未使用无意义的get返回自有对象的函数名包含new/create/find/load/open/keep并且调用方随后调用drop/free/close返回借用对象的函数名不含保留词且调用方未将其存入结构体或长期持有需要长期持有借用对象时已调用keep或制作拷贝数组大小/字符串长度使用size_t数据缓冲区使用unsigned char文件偏移使用int64_t浮点优先float。遵循这套约定不仅是让代码好看更是让 MuPDF 的每个函数签名自带所有权契约函数名本身就是文档。当你在 include/mupdf/fitz/ 下阅读公共头文件如 include/mupdf/fitz/document.h时仅凭fz_open_*、fz_keep_*、fz_drop_*、fz_lookup_*的前缀组合就能在几秒内判断每个 API 的调用与释放义务这是理解这个大型 C 代码库最高效的入门路径。赞分享图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载相关推荐MuPDF 编码风格指南SumatraPDF 所依赖的 C 库命名、类型与引用计数规范MuPDF 编码风格指南SumatraPDF 所依赖的 C 库命名、类型与引用计数规范 MuPDF 是一个轻量级、高性能的 PDF 渲染库也是 Sumatr桌面应用文档Cosmos 项目 Ruby 编码风格指南从缩进、命名到异常与正则的完整规范Cosmos 项目 Ruby 编码风格指南从缩进、命名到异常与正则的完整规范 本指南脱胎于 Cosmos 项目仓库中 guides/coding_style/教程示例工程coreboot C 编码风格指南从缩进、命名到错误处理与内存分配的全量规范解析coreboot C 编码风格指南从缩进、命名到错误处理与内存分配的全量规范解析 导读 本文以 Documentation/contributing/codi系统底层与硬件嵌入式上一篇从单商户到多门店yshop意象商城系统的灵活架构设计揭秘下一篇零代码实现演唱会门票自动抢票GitHub_Trending/ti/ticket-purchase全流程部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考