上位機程式設計編碼規範

张杰net發表於2024-11-19
程式設計

1.大小寫規範

檔名全部小寫是一種廣泛使用的命名約定，特別是在跨平臺開發和開源專案中。主要原因涉及技術約束、可讀性和一致性等方面。以下是原因和優劣勢的詳細分析：

1. 避免跨平臺問題

  • 不同作業系統對檔名的大小寫處理方式不同：
    • Linux/Unix：區分大小寫（myfile.h 和 MyFile.h 是不同檔案）。
    • Windows/macOS：不區分大小寫（兩者會被視為同一檔案）。
  • 如果專案需要跨平臺執行，使用全小寫檔名可以避免檔名衝突或載入失敗的問題，特別是在程式碼倉庫中常見。

2. 提高可讀性

  • 小寫檔名簡單直觀，適合大量檔案快速查詢。
  • 避免了混合大小寫可能導致的歧義或視覺複雜性。

3. 一致性和規範

  • 全小寫是一種約定俗成的風格，在許多大型開源專案中（如 Linux 核心、Python 標準庫）被廣泛使用。
  • 使用一致的命名風格有助於團隊協作和程式碼維護。

4. 減少輸入複雜性

  • 對開發者而言，全小寫檔名減少了在鍵盤上切換大小寫的需求，提高了效率。

5. 配合副檔名

  • 通常檔名小寫配合小寫副檔名（如 .h, .cpp, .json），使整體風格統一：
    main.cpp
config.json
utils.h

劣勢

  1. 不夠直觀：

    • 對於複雜的模組或類，全部小寫的檔名可能降低語義清晰度。
    • 示例：parserconfig.cpp vs ParserConfig.cpp，後者可能更易理解。

  2. 不符合某些專案習慣：

    • 如 Qt 的檔名通常使用 PascalCase，與類名保持一致，方便檔案與類的直接關聯。

適用場景

  1. 全小寫檔名的典型場景：

    • 開源專案（Linux 核心、開源庫等）。
    • 配置檔案或資原始檔：
      • settings.json
      • logo.png
    • 小型或工具類專案（簡單直接，檔名通常描述模組功能）。

  2. 大小寫混合的典型場景：

    • 物件導向程式設計，檔名對應類名（如 Qt）。
    • 框架開發或企業內部專案，檔案命名需反映模組層級。

案例分析

全小寫檔名：

  • Linux 核心：

    • 檔名如：main.c, sched.c, config.h
    • 風格：
      • 清晰、簡單、無歧義。
      • 不直接對應類名，而是按功能模組劃分。

  • Python 標準庫：

    • 檔名如：os.py, socket.py, configparser.py

類名一致的檔名（大小寫混合）：

  • Qt：

    • 檔名如：MainWindow.cpp, MainWindow.h
    • 風格：
      • 檔名與類名一致，有助於在物件導向開發中快速定位。

  • C# 專案：

    • 檔名如：DataService.cs, UserModel.cs
    • 風格：
      • 與類名、名稱空間一一對應，模組結構清晰。

總結建議

  1. 根據專案型別選擇風格：

    • 如果是跨平臺工具類或開源專案，建議使用全小寫風格。
    • 如果是物件導向的企業專案，建議檔名與類名一致，使用 PascalCase。

  2. 保持一致性：

    • 專案中應統一命名風格，無論是全小寫還是大小寫混合，以避免混亂。

  3. 團隊協作：

    • 在團隊開發中，可在專案初期透過編碼規範文件明確檔案命名規則。

2.Qt相關命名

Qt 的命名規範是基於清晰、簡潔和一致性的原則設計的，方便開發者閱讀和維護程式碼。以下是 Qt 的命名規則和推薦的最佳實踐：

1. 類名

  • 規則：使用 PascalCase（首字母大寫，每個單詞的首字母都大寫）。

  • 示例：

    • QWidget
    • QMainWindow
    • QString

  • 自定義類名：

    • 應與 Qt 內建類區分開，可在類名前加自定義字首。
    • 示例：
      • 專案名為 MyApp：
        • MyAppWindow
        • MyAppButton

2. 變數名

  • 規則：使用 camelCase（小寫開頭，每個單詞的首字母大寫）。

  • 成員變數：

    • 前加字首 m_ 表示成員變數，避免與區域性變數衝突。
    • 示例：
      class MyClass {
private:
    int m_value;
    QString m_name;
};

  • 靜態變數：

    • 前加字首 s_ 表示靜態變數。
    • 示例：
      static int s_counter;

  • 區域性變數：

    • 使用純 camelCase，無字首。
    • 示例：
      int counter = 0;

3. 函式名

  • 規則：使用 camelCase，首字母小寫，每個單詞的首字母大寫。

  • 示例：

    • void calculateSum();
    • QString getUserName();
    • bool isValid();

  • 特殊約定：

    • setter 和 getter 函式：
      • setter：set<PropertyName>()，如 setName()。
      • getter：get<PropertyName>() 或直接使用屬性名，如 name()。
    • 布林值相關函式通常以 is 或 has 開頭：
      • bool isRunning();
      • bool hasError();

4. 宏定義

  • 規則：使用 全大寫，單詞間用下劃線分隔（SNAKE_CASE）。

  • 示例：

    #define MY_CUSTOM_MACRO
#define MAX_BUFFER_SIZE 1024

  • Qt 內建宏：

    • 以 Q_ 開頭，如 Q_OBJECT, Q_PROPERTY.

5. 列舉型別

  • 規則：列舉型別名使用 PascalCase，列舉值使用 PascalCase 或全大寫（根據風格）。

  • 示例：

    enum Color {
    Red,
    Green,
    Blue
};

    或：

    enum ErrorCode {
    ERROR_NONE,
    ERROR_NOT_FOUND,
    ERROR_INVALID
};

  • 列舉類（C++11 引入的 enum class）推薦使用 PascalCase：

    enum class LogLevel {
    Debug,
    Info,
    Warning,
    Error
};

6. 名稱空間

  • 規則：名稱空間使用 小寫，單詞間用下劃線分隔（snake_case）。
  • 示例：
    namespace my_app {
    class MainWindow { ... };
}

7. 訊號和槽

  • 規則：訊號和槽函式名使用 camelCase，與普通函式一致。
  • 示例：
    • 訊號：
      signals:
    void dataChanged();
    void errorOccurred(int errorCode);
    • 槽：
      slots:
    void onButtonClicked();
    void handleDataUpdate();

8. 檔名

  • 規則：

    • 考慮到跨平臺的需求，全部為小寫
    • 標頭檔案副檔名為 .h，原始檔副檔名為 .cpp。
    • 示例：
      • 類名 MainWindow：
        • mainwindow.h
        • mainwindow.cpp

  • 特殊檔案：

    • 與 Qt 模組相關的檔案通常有明確的字首：
      • mainwindow.ui（UI 檔案）
      • resources.qrc（資原始檔）

9. 常量

  • 規則：使用 kPascalCase（以 k 開頭，PascalCase 命名）。
  • 示例：
    const int kMaxValue = 100;
const QString kDefaultName = "QtUser";

10. 命名約定示例彙總

以下是一個符合 Qt 命名規範的程式碼片段：

#ifndef MYCLASS_H
#define MYCLASS_H

#include <QObject>
#include <QString>

class MyClass : public QObject {
    Q_OBJECT

public:
    explicit MyClass(QObject *parent = nullptr);
    ~MyClass();

    void setName(const QString &name);
    QString name() const;

signals:
    void nameChanged();

private:
    QString m_name;
    static int s_instanceCount;
};

#endif // MYCLASS_H

11. Qt 風格檢查工具

  • Clazy：Qt 的靜態程式碼分析工具，可幫助檢測違反命名規範或其他潛在問題。
  • Clang-Tidy：支援配置規則，適合 C++ 開發者。

透過遵守以上規範，可以提高程式碼的可讀性和一致性。如果有特定需求或專案風格，也可以在此基礎上進行調整！ 😊

3.json檔案命名

在命名 JSON 檔案時，建議遵循清晰、簡潔和一致的命名規則，以便更易於理解和管理。以下是一些常見的命名格式和建議：

1. 一般命名規則

  • 小寫命名
    使用小寫字母，單詞間用下劃線或連字元分隔，便於跨平臺使用，尤其在區分大小寫的系統中（如Linux）。

    • 示例：
      • user_data.json
      • config-settings.json

  • 基於功能命名
    檔名應該能明確表示檔案的內容或用途。

    • 示例：
      • settings.json（通用配置）
      • user_profiles.json（使用者資料）
      • error_log.json（錯誤日誌）

  • 新增時間戳（可選）
    對需要區分版本或生成時間的檔案，建議新增時間戳，格式一般為YYYYMMDD或YYYY-MM-DD。

    • 示例：
      • backup_20241118.json
      • report-2024-11-18.json

  • 新增環境標識（可選）
    區分開發、測試和生產環境時，可在檔名中包含環境標識，如dev、test、prod。

    • 示例：
      • config_dev.json
      • settings_prod.json

2. 命名格式建議

a. 下劃線格式 (snake_case)

  • 常見於後端開發和Linux系統。
    • 示例：app_config.json, user_data_backup.json

b. 連字元格式 (kebab-case)

  • 常見於前端開發，符合Web檔名習慣。
    • 示例：app-config.json, user-data.json

c. 駝峰式格式 (camelCase)

  • 用於JavaScript或其他以駝峰式為主的專案中，但不建議用作檔名（相容性較差）。
    • 示例：appConfig.json, userData.json

d. PascalCase格式

  • 少用，可能適合特殊命名需求。
    • 示例：AppConfig.json, UserData.json

3. 實際應用場景

a. 配置檔案

  • 檔名：config.json, app_settings.json, database_config.json
  • 用途：儲存應用程式的配置資料。

b. 日誌檔案

  • 檔名：error_log_20241118.json, system_status.json
  • 用途：記錄系統執行狀態或錯誤資訊。

c. 資料檔案

  • 檔名：user_profiles.json, sales_data_2024.json
  • 用途：儲存業務相關的結構化資料。

d. 國際化檔案

  • 檔名：en_us.json, zh_cn.json, fr_fr.json
  • 用途：用於儲存多語言翻譯內容。

4. 不建議的命名方式

  • 空格
    檔名中不要使用空格，用下劃線或連字元替代。

    • 不推薦：user data.json
    • 推薦：user_data.json 或 user-data.json

  • 特殊字元
    避免使用如 !@#$%^&*() 等特殊字元，可能引發跨平臺相容性問題。

  • 過長的檔名
    避免檔名過長，限制在 30 字元以內為宜，保持簡潔。

總結命名模板

<用途>_<模組名>_<時間戳>_<環境標識>.json
  • 示例：
    • config_dev_20241118.json（開發環境配置檔案）
    • user_profiles_2024.json（使用者資料）
    • error_log_test.json（測試環境錯誤日誌）

如果需要更具體的建議，請告訴我您的場景！ 😊

4.json變數命名

JSON 檔案內部的鍵值對命名是保證資料結構清晰、可維護的關鍵。不同場景中可能需要不同的命名規則，但通常遵循一致性和規範化原則。以下是具體建議和常見命名方式：

1. 一般命名規則

a. 使用小寫或駝峰式（camelCase）

  • 小寫+下劃線（snake_case）

    • 常用於後端開發，清晰易讀，適合靜態配置或跨語言系統。
    • 示例：user_name, account_status, created_at

  • 駝峰式（camelCase）

    • 常用於前端開發或動態語言（如JavaScript），更符合JSON的流行風格。
    • 示例：userName, accountStatus, createdAt

b. 避免空格和特殊字元

  • 鍵名中不要使用空格或特殊字元。
    • 不推薦：user name, account-status!
    • 推薦：user_name 或 userName

c. 使用簡潔且具有描述性的名稱

  • 確保鍵名簡短，同時清晰地表達其意義。
    • 不推薦：userAllDetails
    • 推薦：user_info 或 user_details

d. 保持一致性

  • 在同一檔案或專案中，始終遵循統一的命名規則（如所有鍵均使用snake_case或camelCase）。

2. 常見命名方式

a. 時間和日期欄位

  • created_at 或 createdAt（建立時間）
  • updated_at 或 updatedAt（更新時間）
  • last_login 或 lastLogin（最後登入時間）
  • 格式值通常為 ISO 8601 標準，例如："2024-11-18T12:30:00Z"

b. 使用者相關

  • user_id 或 userId（使用者ID）
  • user_name 或 userName（使用者名稱）
  • email（郵箱）
  • phone_number 或 phoneNumber（電話號碼）

c. 狀態或標誌

  • is_active 或 isActive（是否活躍，布林值）
  • status（狀態，例如：active, inactive）
  • error_code 或 errorCode（錯誤碼）

d. 其他常用欄位

  • 數字欄位：price, count, quantity
  • 位置欄位：latitude, longitude, address
  • 配置欄位：config_version, setting_name

3. 命名約定示例

a. 小寫+下劃線風格（snake_case）

{
  "user_id": 123,
  "user_name": "Alice",
  "email": "alice@example.com",
  "created_at": "2024-11-18T12:30:00Z",
  "is_active": true
}

b. 駝峰式（camelCase）

{
  "userId": 123,
  "userName": "Alice",
  "email": "alice@example.com",
  "createdAt": "2024-11-18T12:30:00Z",
  "isActive": true
}

c. PascalCase（不常用，但部分場景適合）

{
  "UserId": 123,
  "UserName": "Alice",
  "Email": "alice@example.com",
  "CreatedAt": "2024-11-18T12:30:00Z",
  "IsActive": true
}

4. 鍵值對分類及分組

  • 分層結構：將相關資料分組，避免平鋪式結構造成混亂。
    • 不推薦：
      {
  "user_id": 123,
  "user_name": "Alice",
  "address_street": "Main St",
  "address_city": "New York"
}
    • 推薦：
      {
  "user_id": 123,
  "user_name": "Alice",
  "address": {
    "street": "Main St",
    "city": "New York"
  }
}

5. 值的型別

  • 布林值：用is_或has_字首命名，表示狀態或屬性。

    • 示例：is_active, has_access

  • 列表或陣列：用複數形式命名鍵。

    • 示例：users, products, order_items

  • 數值：儘量明確表示單位（如價格、長度）。

    • 示例：price_usd, length_cm

6. 命名模板

<實體>_<描述>_<屬性>
  • 示例：
    • user_name（使用者的名稱）
    • order_total_price（訂單總價）
    • device_status（裝置狀態）

透過這些規則和示例，你可以設計清晰、易讀的 JSON 鍵值對結構。如果有具體的應用場景，可以進一步最佳化！ 😊

相關文章