上位机编程命名规范

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_OBJECTpublic: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": "[e-mail]","created_at": "2024-11-18T12:30:00Z","is_active": true
}

b. 驼峰式（camelCase）

{"userId": 123,"userName": "Alice","email": "[e-mail]","createdAt": "2024-11-18T12:30:00Z","isActive": true
}

c. PascalCase（不常用，但部分场景适合）

{"UserId": 123,"UserName": "Alice","Email": "[e-mail]","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 键值对结构。如果有具体的应用场景，可以进一步优化！ 😊