Qt上位机编程命名规范

1.大小写命名分析

文件名全部小写是一种广泛使用的命名约定，特别是在跨平台开发和开源项目中。主要原因涉及技术约束、可读性和一致性等方面。以下是原因和优劣势的详细分析：

1.1. 避免跨平台问题

不同操作系统对文件名的大小写处理方式不同:

• Linux/Unix：区分大小写（myfile.h 和 MyFile.h 是不同文件）。
• Windows/macOS：不区分大小写（两者会被视为同一文件）。

1.2. 提高可读性

• 小写文件名简单直观，适合大量文件快速查找。
• 避免了混合大小写可能导致的歧义或视觉复杂性。

1.3. 一致性和规范性

• 全小写是一种约定俗成的风格，在许多大型开源项目中（如 Linux 内核、Python 标准库）被广泛使用。
• 使用一致的命名风格有助于团队协作和代码维护。

1.4. 配合文件扩展名

• 通常文件名小写配合小写扩展名（如 .h, .cpp, .json），使整体风格统一：

main.cpp
config.json
utils.h

1.5.劣势

• 不够直观，parserconfig.cpp vs ParserConfig.cpp，后者可能更易理解。
• 不符合某些项目习惯， 有写项目文件名使用PascalCase命名方式，方便文件与类直接关联

1.6. 总结

• 如果是跨平台工具类或开源项目，建议使用全小写风格
• 项目中应统一命名风格，无论是全小写还是大小写混合，以避免混乱
• 在团队开发中，可在项目初期通过编码规范文档明确文件命名规则

2.代码命名规范

Qt 的命名规范是基于清晰、简洁和一致性的原则设计的，方便开发者阅读和维护代码。以下是 Qt 的命名规则和推荐的最佳实践：

2.1.类名

• 规则：使用 PascalCase（首字母大写，每个单词的首字母都大写）。
• 示例：
  • QWidget
  • QMainWindow
  • QString

2.2文件名

• 规则：

  • 考虑到跨平台的需求，全部为小写
  • 头文件扩展名为 .h，源文件扩展名为 .cpp。

• 示例：

  • 类名 MainWindow：
    • mainwindow.h
    • mainwindow.cpp

• 特殊文件：

  • 与 Qt 模块相关的文件通常有明确的前缀：
    • mainwindow.ui（UI 文件）
    • resources.qrc（资源文件）

2.3. 变量名

• 规则：使用 camelCase（小写开头，每个单词的首字母大写）。

• 成员变量：

  • 前加前缀 m_ 表示成员变量，避免与局部变量冲突。
  • 示例：

    class MyClass {
    private:
        int m_value;
        QString m_name;
    };
    

• 静态变量：

  • 前加前缀 s_ 表示静态变量。
  • 示例：

    static int s_counter;
    

• 局部变量：

  • 使用纯 camelCase，无前缀。
  • 示例：

    int counter = 0;
    

2.4. 函数名

• 规则：使用 camelCase，首字母小写，每个单词的首字母大写。

• 示例：

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

• 特殊约定：

  • setter 和 getter 函数：
    • setter：set<PropertyName>()，如 setName()。
    • getter：get<PropertyName>() 或直接使用属性名，如 name()。
  • 布尔值相关函数通常以 is 或 has 开头：
    • bool isRunning();
    • bool hasError();

2.4. 宏定义

• 规则：使用 全大写，单词间用下划线分隔（SNAKE_CASE）。
• 示例：

  #define MY_CUSTOM_MACRO
  #define MAX_BUFFER_SIZE 1024
  

• Qt 内置宏：
  • 以 Q_ 开头，如 Q_OBJECT, Q_PROPERTY.

2.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
  };
  

2.6. 命名空间

• 规则：命名空间使用 小写，单词间用下划线分隔（尽量简洁）。
• 示例：

  namespace my_app {
      class MainWindow { ... };
  }
  

2.7. 信号和槽

• 规则：信号和槽函数名使用 camelCase，与普通函数一致。
• 示例：
  • 信号：

    signals:
        void dataChanged();
        void errorOccurred(int errorCode);
    

  • 槽：

    slots:
        void onButtonClicked();
        void handleDataUpdate();
    

2.8. 常量

• 规则：使用 kPascalCase（以 k 开头，PascalCase 命名）。
• 示例：

  const int kMaxValue = 100;
  const QString kDefaultName = "QtUser";
  

2.9.include顺序

1. 按照 系统头文件、Qt 库头文件、自定义头文件 的顺序组织 #include。
2. 避免包含整个模块，只包含需要的头文件。
3. 使用前向声明 来减少不必要的依赖。
4. 使用 #pragma once 或 包含保护 来防止重复包含。
5. 根据 Qt 模块划分头文件，组织清晰。
6. 避免冗余和重复的包含。

示例：

// MyClass.cpp
#include <iostream>          // 标准库文件
#include <vector>

#include <boost/asio.hpp>    // 第三方库文件

#include <QWidget>           // Qt 库文件
#include <QPushButton>

#include "MyClass.h"         // 当前文件的头文件
#include "Helper.h"          // 同模块自定义头文件

2.9.总结

以下是一个符合 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

3.json配置命名规范

在命名 JSON 文件时，建议遵循清晰、简洁和一致的命名规则，以便更易于理解和管理。以下是一些常见的命名格式和建议：

3.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

3.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.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
• 用途：用于存储多语言翻译内容。

3.4. 不建议的命名方式

• 空格
  文件名中不要使用空格，用下划线或连字符替代。

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

• 特殊字符
  避免使用如 !@#$%^&*() 等特殊字符，可能引发跨平台兼容性问题。

• 过长的文件名
  避免文件名过长，限制在 30 字符以内为宜，保持简洁。

3.4. json命名规则

• 小写+下划线（snake_case）

  • 常用于后端开发，清晰易读，适合静态配置或跨语言系统。
  • 示例：user_name, account_status, created_at

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

• 驼峰式（camelCase）

  • 常用于前端开发或动态语言（如JavaScript），更符合JSON的流行风格。
  • 示例：userName, accountStatus, createdAt

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

3.5.总结

<用途>_<模块名>_<时间戳>_<环境标识>.json

• 示例：
  • config_dev_20241118.json（开发环境配置文件）
  • user_profiles_2024.json（用户数据）
  • error_log_test.json（测试环境错误日志）

4.ini配置命名规范

4.1.不同格式分析

4.2.建议

• 如果配置文件是扁平化设计或层级较浅，推荐使用 _ 分隔，保持简单直观。
• 如果配置文件需要表示复杂嵌套关系，建议采用 / 或 . 表示层级，并在键名的顶层分组下使用 _ 分隔子键。

4.3.综合示例

• 键名扁平化设计
  适合小型配置或无需表示复杂结构的场景：

  user_name=John
  user_age=30
  display_resolution_width=1920
  display_resolution_height=1080
  

• 键名分层结合下划线
  适合大型项目，顶层使用分组，子键使用下划线：

  [general]
  user_name=John
  user_age=30
  
  [display_resolution]
  width=1920
  height=1080