From a9f63eea9d3f5aada0627df8566a48a377cdf310 Mon Sep 17 00:00:00 2001
From: pjh456 <147148383@qq.com>
Date: Sun, 28 Sep 2025 05:03:11 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E4=BA=86=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/CONTRIBUTING.md |  5 +--
 docs/code_style.md   | 95 ++++++++++++++++++++++++++++++++++++--------
 2 files changed, 80 insertions(+), 20 deletions(-)

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index b6aaaa1..b6666d2 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -86,10 +86,7 @@
 
 ## 🔍 Code Review 原则
 
-- 确认代码可读、可维护，避免冗余实现。
-- 注意异常处理、内存管理和线程安全问题。
-- 保证接口一致性和合理性。
-- 审查通过后，才能合并到 `dev` 分支。
+详见 [代码规范](code_style.md)
 
 ---
 
diff --git a/docs/code_style.md b/docs/code_style.md
index c40d849..b217143 100644
--- a/docs/code_style.md
+++ b/docs/code_style.md
@@ -6,27 +6,50 @@
 
 - 使用 **C++17** 或更高版本。
 - 优先使用标准库功能，避免非必要的第三方依赖。
+- 引入第三方依赖时，若有 CMake 或 Github 仓库时应避免直接复制文件于本项目。
 
 ## 2. 文件与目录命名
 
 - 文件名统一小写，单词间用下划线分隔：`event_loop.h`、`tcp_server.cpp`
-- 目录名小写：`include/`、`src/`、`tests/`、`examples/`
-- 头文件包含保护宏：`INCLUDE_OUCSERVER_` + 无后缀文件名，全部字母大写，单词间用下划线分隔
+- 目录名统一小写，单词间用下划线分隔：`include/`、`src/`、`tests/`、`examples/`
+- 头文件包含保护宏：`INCLUDE_OUC_SERVER_` + 无后缀文件名，全部字母大写，单词间用下划线分隔
     ```cpp
-    #ifndef INCLUDE_OUCSERVER_EVENT_LOOP
-    #define INCLUDE_OUCSERVER_EVENT_LOOP
+    #ifndef INCLUDE_OUC_SERVER_EVENT_LOOP
+    #define INCLUDE_OUC_SERVER_EVENT_LOOP
     // ...
-    #endif // INCLUDE_OUCSERVER_EVENT_LOOP
+    #endif // INCLUDE_OUC_SERVER_EVENT_LOOP
     ```
 
-## 3. 类与命名
+## 3. 类型、结构体与枚举类型
 
-- 类名采用 **驼峰命名**：
+- 类名采用 **大驼峰命名**：
     ```cpp
     class EventLoop {};
     class TcpServer {};
     ```
-- 枚举类型使用 **首字母大写的驼峰命名**：
+- 成员变量使用 `m_` 前缀：
+    ```cpp
+    int m_socket_fd;
+    std::string m_host;
+    ```
+- 一般情况下 **不允许** 成员变量对外部可见，若有成员变量的读写需求可采取以下方式：
+    - 使用 `T get_name() const` 与 `void set_name(const T&)` 获取与设置不需要引用的成员变量。
+    > 若有返回错误码的需求，可以改为 `bool set_name(const T&)`。
+    - 使用 `T& name()` 与 `const T& name() const` 获取需要引用的成员变量（与前一种方式 **不共存**）。
+    - 成员变量的读写应当最大程度地确保 **异常安全**，如果满足条件应添加 `noexcept` 签名。
+- 结构体与类型成员变量，若无特殊需求应当放在类型内最前面：
+    ```cpp
+    class Data
+    {
+    private:
+        int data1;
+        char data2;
+    public:
+        Data() = default;
+        // ...
+    }
+    ```
+- 枚举类型使用 **大驼峰命名**：
     ```cpp
     enum class SocketState { Closed, Listening, Connected };
     ```
@@ -36,7 +59,7 @@
 **不允许在全局环境下使用 `using namespace`!**
 
 - 所有模块都需要包含于 `ouc_server` 命名空间
-- 对于一个子模块，应该再包含于以模块的文件夹名为名的命名空间
+- 对于一个子模块，应该再包含于 **以模块的文件夹名为名** 的命名空间
     ```cpp
     namespace ouc_server
     {
@@ -54,16 +77,47 @@
     void start_server();
     int get_socket_fd() const;
     ```
-- 成员变量使用 `m_` 前缀：
+- 若与函数名等重名需要区分时，函数形参名统一使用 `p_` 前缀：
     ```cpp
-    int m_socket_fd;
-    std::string m_host;
+    int data;
+    int do_something(int p_data);
     ```
 - 局部变量尽量短小有意义，避免滥用缩写。
 - 常量使用 **全大写加下划线**：
     ```cpp
     constexpr int MAX_CONNECTIONS = 1024;
     ```
+- 函数声明时，对 **拷贝开销大的** 形参类型应尽可能避免非必要类型转换和拷贝，根据以下原则对 **拷贝开销大的类型** 尽量避免使用`T`：
+    - 需要拷贝一个值而无需修改参数时，使用 `const T&`
+    - 需要传递引用并对参数进行修改时，使用 `T&`
+    - 需要移动一个值，原位置不再使用，使用 `T&&`
+- 应当避免过多的函数形参个数，若有大量参数配置需要应 **封装对应结构体**。
+    ```cpp
+    // Wrong!
+    int do_with_many_args(int x, int y, int z, bool is_active, bool is_open, char* name, std::string port);
+    // Correct
+    struct ConfigData
+    {
+        int x,y,z;
+        bool is_active, is_open;
+        char* name;
+        std::string port;
+    };
+    int do_with_many_args(const ConfigData& p_config);
+    ```
+- 函数形参与实参名在有注释或过长时应当 **全部换行处理**，并在第一个参数前换行。
+    ```cpp
+    int do_something(
+        int this_is_a_veeeeeeeeeeeeeeery_long_var,
+        int and_this_is_another_veeeeery_long_var,
+        int short_but_need_explain_var, /* ... */
+        int final_var);
+    do_something(
+        I_call_thiiiiiiis_function,
+        I_call_it_tooooooooooooooo,
+        I_need_to_be_explain, /* ... */
+        I_am_the_final_one);
+    ```
 
 ## 6. 缩进与空格
 
@@ -72,13 +126,15 @@
     ```cpp
     int sum = a + b;
     ```
-- 控制语句中除单语句外均需要添加大括号作用域：
+- 控制语句中除单语句及 `do while` 外均需要添加大括号作用域：
     - 条件分支
         ```cpp
-        if (condition)
-            do_something();                     // Right
+        // Wrong!
         if(condition)
-            do_something(), do_another_thing(); // Wrong!
+            do_something(), do_another_thing();
+        // Correct
+        if (condition)
+            do_something();
         if (condition)
         {
             do_something();
@@ -92,17 +148,24 @@
         ```
     - 循环结构
         ```cpp
+        for (int i = 0; i < n; ++i)
+            do_something();
         for (int i = 0; i < n; ++i)
         {
             do_something();
+            do_another_thing();
         }
+        while(condition)
+            do_something();
         while(condition)
         {
             do_something();
+            do_another_thing();
         }
         do
         {
             do_something();
+            /* Special: Need {}!*/
         }
         while(condition);
         ```