eBPF for Windows 开发指南：编码规范与最佳实践

eBPF for Windows 开发指南：编码规范与最佳实践

ebpf-for-windows eBPF implementation that runs on top of Windows 项目地址: https://gitcode.com/gh_mirrors/eb/ebpf-for-windows

前言

本文是针对 eBPF for Windows 项目的开发指南，旨在帮助开发者理解并遵循项目的编码规范和开发实践。eBPF（扩展伯克利包过滤器）是一种革命性的内核技术，而 eBPF for Windows 项目将其引入 Windows 平台，为开发者提供了强大的网络和系统监控能力。

编码规范

数据类型与变量

1. 固定长度类型：始终使用 stdint.h 中定义的固定长度类型（如 int64_t、uint8_t），而非编译器决定的关键字（如 long、unsigned char）。这确保了代码在不同平台间的可移植性。

2. 作用域控制：充分利用 const、static 和可见性修饰符来限制变量和方法的暴露范围，提高代码的安全性和模块化程度。

3. 全局变量：尽量避免使用全局变量，以减少代码的耦合度和潜在的错误。

命名约定

1. 命名风格：

   • 变量、成员和函数名使用 lower_snake_case
   • 宏和常量使用 UPPER_SNAKE_CASE
   • 文件名优先使用 lower_snake_case

2. 完整性原则：优先使用完整单词而非缩写（如 memory_context 而非 mem_ctx），除非是广泛认可的术语（如 "app"、"info"）。

3. 私有标识符：

   • 使用 _ 前缀表示内部和私有字段或方法（如 _internal_field）
   • 单个 _ 保留给局部定义（静态、文件作用域定义）

4. 结构体定义：

   • 结构体定义使用 _ 前缀
   • 同时创建带有 _t 后缀的 typedef

   typedef struct _ebpf_widget {
       uint64_t count;
   } ebpf_widget_t;
   

5. 命名空间：所有 eBPF 相关的全局命名空间标识符应使用 ebpf_ 前缀（如 ebpf_result_t）。

代码注释

1. Doxygen 注释：所有公共 API 头文件必须使用 Doxygen 注释，并包含 [in,out] 方向注解。内部 API 头文件也鼓励但不强制使用。

2. 避免注释代码：不要保留被注释掉的代码或使用 #if 0 包裹的代码，确保所有代码都是实际构建的一部分。

头文件规范

1. 自包含原则：确保任何头文件都可以直接包含，不需要预先包含其他头文件。所有依赖项应在头文件内部处理。

2. 包含顺序：

   • 先包含本地头文件（使用 ""）
   • 再包含系统头文件（使用 <>）
   • 尽可能按字母顺序排列包含的头文件

3. 防止重复包含：使用 #pragma once 而非传统的 #ifdef 防护宏。

代码风格与格式化

自动化格式化

项目使用 clang-format（特定版本 18.1.8）来强制执行代码格式化规则。在修改 C/C++ 文件后，提交前应运行：

./scripts/format-code

格式化规则

1. 基础标准：遵循 LLVM 编码标准，但有如下例外：

   • 源代码行不得超过 120 个字符
   • 单行 if/else/循环块必须用大括号括起来

2. 编辑器集成：建议配置编辑器自动运行 clang-format：

   • Emacs：使用 clang-format.el
   • Vim：使用 vim-clang-format
   • VS Code：使用 vscode-cpptools

3. 格式文件：项目根目录下的 .clang-format 文件定义了具体的格式化规则，基于 LLVM 风格但更接近 Visual Studio 默认风格。

许可证声明

每个代码文件顶部必须包含以下许可证声明：

// Copyright (c) eBPF for Windows contributors
// SPDX-License-Identifier: MIT

可以使用脚本检查所有文件是否包含此声明：

./scripts/check-license

最佳实践

1. 魔术数字：避免使用硬编码的魔术数字，对于需要在不同文件间保持一致的值，应使用 #define、enum 或 const 值。

2. 函数重载：尽量避免在项目中使用相同函数名但不同原型的 C 函数。

3. 一致性原则：如果文件中已有特定风格（如私有成员命名为 m_member 而非 _member），应优先遵循现有风格而非本指南。

结语

遵循这些编码规范和最佳实践将有助于保持 eBPF for Windows 项目代码的一致性和可维护性。作为开发者，理解并应用这些规则不仅有助于项目发展，也能提升个人代码质量。记住，良好的编码习惯是高效协作的基础。

ebpf-for-windows eBPF implementation that runs on top of Windows 项目地址: https://gitcode.com/gh_mirrors/eb/ebpf-for-windows