API/SDK 通用接口文件问题点释疑以及使用建议

1. 接口函数命名是否恰当。

如果是直接返回要获取的数据，直接使用该数据的名字来命名函数：

const String& version(void) const;

如果是通过参数返回要获取的数据，则在该数据名字前加一个get

SystemStatus getVersion(String& strVer) const;

基于上一条，如果这里获取version没有失败风险，可以采用：

void getVersion(String& strVer) const;

2. 对接口函数参数的修饰

对于输入参数，建议尽量通过const&代替指针传递。输入参数一般是那些不会被函数修改的参数。

说明： 用 & 修饰，可以避免传值给函数过程中的复制以及函数返回后的副本销毁，这可以节省调用对象的拷贝构造函数和析构函数的开销；被 const 修饰，这样具有仅传递指向对象的指针、同时确保对象不会被方法修改的效果。

例外： 这条规则仅适用于对象，对于诸如int,bool,double等内建类型不适用，它们本身值已经很小了，可以直接放进 CPU 寄存器。此外，STL 迭代器和函数对象是采用传值方式，也不适用这条规则。

std::string stringToLower(const std::string& str);

对于输出参数，建议选用指针代替非cosnt引用，这样才能将他们的易变性清晰的告知客户。

3. 对接口函数返回值的说明

对接口函数返回值主要有两种情况：以传值方式返回，或者是以 const& 进行返回。

前者的返回模式我们已熟知，现在主要看看后者：

一般用户如果将结果以引用进行返回，大多数是为了避免传值过程中会导致的拷贝构造，造成的内存开销。在此基础上用const修饰，是以引用对象的内部状态基础上，避免后续被修改以影响类的任何内部状态。

当然，如果是以值进行传递，是不需要用 const 修饰的，因为返回的对象本身是一个副本，修改它不会影响类的任何内部状态。
另一种情况，如果是返回指向私有数据成员的指针或者引用，那就应该把结果声明为 const ，否则用户能不通过公有 API 而修改对象的内部状态。在这种情况下，还必须考虑返回的指针或引用是否会比类存在的更长久。如果有这个可能，就应该考虑返回一个引用计数的指针。

不过有一种情况下是不能通过引用形式进行返回，就是返回作用域在函数内部的局部变量，出了函数就被销毁了，这时候采用引用，是一件危险的行为。

建议： 在不确定或者安全比性能更重要的情况下，建议传值方式返回结果，这样既不必担心用户在对象被销毁后仍继续持有引用，也不会因返回 const& 而破坏封装性；在更关注性能的场景，建议选用 const& 的方法，毕竟确实能提高不少性能。

4. 几类变量命名写法的约定：

• ObjectId 类型的变量以 id 开头
• 指针类型变量命名以p开头
• 成员变量命名以m开头，有两种写法均可m_xxx or mXxx，但在同一模块中请统一
• 成员变量是指针情况，以 m_pName 写法为准
• ZBOOL 类型变量命名，以 b 开头
• 枚举类型常量，以k开头

5. 不要使用原生的基础类型，尽量使用封装之后的类型

NO : bool, size_t, uint32_t, etc…
YES :ZBOOL, ZUINT64, ZINT, ZINT32, ZBYTE, ZTCHAR, etc…

例外：C++ 运算符重载的返回值不采用 ZBOOL， 采用C++原生 bool 类型。

6. 引用符号 & 统一贴近类型，而不是变量。

eg:Point3dArray& points.

7.几类常见的细节问题：

• 派生类的析构函数需加上 override
• 派生类覆写的接口函数，需加上override
• 派生类的虚函数，要加上virtual
• ZCRX_DECLARE_MEMBERS(xxx) 中描述的对象，要加上命名空间
• 禁止硬编码
• 禁止魔鬼数字
• 常量字符串在使用时，得考虑宽窄字节问题，是否要加上ZW_T("xxx")
• 禁用 sealed ,替换为 final
• 将游离在 ZSoft 命名空间外的类，归于 ZSoft 命名空间之下。
• NO :#pragma warning diaable YES:#pragma waning push && #pragma warning pop,显式指定范围。

8. 返回值是用 ZBOOL 还是 SystemStatus 的说明

当函数意图简单，结构简单，能一眼看出其设计思路的情况下，就简原则，采用 ZBOOL

BOOL isTure(void) const;

当函数意图丰富，或者为了表达更丰富的函数执行结果信息，比如找不到名字，输入参数不合法等等，建议采用SystemStatus

SystemStatus removeExtensionByName(const String& name);

9. 接口类 + 实现类的封装模式要求接口类的构造函数指明与其派生层次对应的实现类指针。

10. 内存对齐

• 定义具有成员变量的类和结构体头文件，应显式采用 #pragma pack(push, x) and #pragma pack(pop) 来指定内存对齐。
• 定义具有成员变量的类和结构体需对成员变量优先考虑按内存对齐形式排序。