上位机编程编码规范

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
```

劣势

不够直观：
- 对于复杂的模块或类，全部小写的文件名可能降低语义清晰度。
- 示例：parserconfig.cpp vs ParserConfig.cpp，后者可能更易理解。
不符合某些项目习惯：
- 如 Qt 的文件名通常使用 PascalCase，与类名保持一致，方便文件与类的直接关联。

适用场景

全小写文件名的典型场景：
- 开源项目（Linux 内核、开源库等）。
- 配置文件或资源文件：
  - settings.json
  - logo.png
- 小型或工具类项目（简单直接，文件名通常描述模块功能）。
大小写混合的典型场景：
- 面向对象编程，文件名对应类名（如 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
- 风格：
  - 与类名、命名空间一一对应，模块结构清晰。

总结建议

根据项目类型选择风格：
- 如果是跨平台工具类或开源项目，建议使用全小写风格。
- 如果是面向对象的企业项目，建议文件名与类名一致，使用 PascalCase。
保持一致性：
- 项目中应统一命名风格，无论是全小写还是大小写混合，以避免混乱。
团队协作：
- 在团队开发中，可在项目初期通过编码规范文档明确文件命名规则。

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"
}

5. 值的类型

布尔值：用is_或has_前缀命名，表示状态或属性。
- 示例：is_active, has_access
列表或数组：用复数形式命名键。
- 示例：users, products, order_items
数值：尽量明确表示单位（如价格、长度）。
- 示例：price_usd, length_cm

6. 命名模板

<实体>_<描述>_<属性>

示例：
- user_name（用户的名称）
- order_total_price（订单总价）
- device_status（设备状态）

通过这些规则和示例，你可以设计清晰、易读的 JSON 键值对结构。如果有具体的应用场景，可以进一步优化！ 😊

posted @ 2024-11-19 08:00 张杰net 阅读(8) 评论(0) 编辑收藏举报

刷新页面返回顶部

ahsczj

上位机编程编码规范

1.大小写规范

1. 避免跨平台问题

2. 提高可读性

3. 一致性和规范

4. 减少输入复杂性

5. 配合文件扩展名

劣势

适用场景

案例分析

全小写文件名：

类名一致的文件名（大小写混合）：

总结建议

2.Qt相关命名

1. 类名

2. 变量名

3. 函数名

4. 宏定义

5. 枚举类型

6. 命名空间

7. 信号和槽

8. 文件名

9. 常量

10. 命名约定示例汇总

11. Qt 风格检查工具

3.json文件命名

1. 一般命名规则

2. 命名格式建议

a. 下划线格式 (snake_case)

b. 连字符格式 (kebab-case)

c. 驼峰式格式 (camelCase)

d. PascalCase格式

3. 实际应用场景

a. 配置文件

b. 日志文件

c. 数据文件

d. 国际化文件

4. 不建议的命名方式

总结命名模板

4.json变量命名

1. 一般命名规则

a. 使用小写或驼峰式（camelCase）

b. 避免空格和特殊字符

c. 使用简洁且具有描述性的名称

d. 保持一致性

2. 常见命名方式

a. 时间和日期字段

b. 用户相关

c. 状态或标志

d. 其他常用字段

3. 命名约定示例

a. 小写+下划线风格（snake_case）

b. 驼峰式（camelCase）

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

4. 键值对分类及分组

5. 值的类型

6. 命名模板

公告