Qt上位机编程命名规范-执行版

主要规范原则参考Qt上位机编程命名规范。

1.文件/文件夹大小写分析

考虑跨平台性，全小写是一种约定俗成的风格，在许多大型开源项目中（如 Linux 内核、Python 标准库）被广泛使用。

1.1. 配合文件扩展名

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

 main.cpp
 config.json
 utils.h

1.2.文件夹和pri文件命名

通常小写、下划线分开：

 control_panel
 control_panel/control_panel.pri

2.代码命名规范

2.1.类名

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

2.2. 变量名

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

• 成员变量：

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

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

• 静态变量：

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

    static int s_counter;
    

• 局部变量：

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

    int counter = 0;
    

2.3. 函数名

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

• 示例：

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

• 特殊约定：

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

• 虚函数：

写法	是否推荐	说明
virtual void Execute();	⛔️	仅声明为虚函数，但不一定是重写
void Execute() override;	✅	编译器可验证重写，但不显示虚性质
virtual void Execute() override;	✅✅	✔ 表示虚函数 ✔ 表示重写 ✔ 最清晰的写法

2.4. 枚举类型

• 规则：枚举类型名使用 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.5. 命名空间

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

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

2.6. 信号和槽

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

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

  • 槽：

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

2.7. 常量

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

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

2.8.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.配置命名规范

3.1. 一般命名规则

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

• 小写命名
  使用小写字母，单词间用下划线分隔，便于跨平台使用，尤其在区分大小写的系统中（如Linux）。

  • 示例：
    • user_data.json

• 添加时间戳（可选）
  对需要区分版本或生成时间的文件，建议添加时间戳，格式一般为YYYY_MM_DD。

  • 示例：
    • report_2024_11_18.json

3.2. 命名格式建议

下划线格式 (snake_case) 我现在就是这个标准

• 常见于后端开发和Linux系统。
  • 示例：app_config.json, user_data_backup.json

3.3. json命名规则

• 驼峰式（camelCase）
  • 常用于前端开发或动态语言（如JavaScript），更符合JSON的流行风格，同时更加兼容Qt中的变量命名风格。
  • 示例：userName, accountStatus, createdAt

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

3.4. ini配置命名规范

适合大型项目，建议使用 isAdmin（驼峰命名),也是为了 兼容Qt中的变量命名风格：
文件命名：
- 示例：app_config.ini user_data_backup.ini

[general]
userName=John
userAge=30

[displayResolution]
width=1920
height=1080