﻿/*
	© 2009-2016 FrankHB.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file Designation.txt
\ingroup Documentation
\brief 项目设计规则指定和说明。
\version r9855
\author FrankHB <frankhb1989@gmail.com>
\since 早于 build 132
\par 创建时间:
	2009-12-02 05:14:30 +0800
\par 修改时间:
	2016-06-08 07:23 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::Designation
*/


/*

@0 体例和适用范围：
引用标记参见 [Documentation::CommonRules @@0.1] 。
项目规则、整体结构和适用范围参见 [Documentation::ProjectRules] 。本文档是其具体实现和补充。
其它说明和使用方法参见 https://bitbucket.org/FrankHB/yslib/wiki 。

@1 需求(requirements) 和可行性(feasibility) ：

@1.1 基本原理和表达形式：
出发点：构建一个可复用的组件组成的库框架。
代码不保证语义角度（例如实现需求）内容的连贯性。
原始目的：在以标准 C++ 环境（宿主实现或独立实现）为基础的嵌入式设备等平台上，建立常规应用程序框架。
扩展目的：渐进地向独立的计算机软件系统演进，探究具有高度互操作性的系统的一般实现方法。

@1.2 理论背景、工具和依据：
基本内容参见 [Documentation::CommonRules @@2.1] 。

@1.3 内联需求分析：
为减少规约冗余，其它任何没有在本章明确的需求和具体规格，包括但不限于以下项，由设计(@2) 直接或间接定义：
特定组件集合的适用范围；
特定组件集合的环境限制和要求；
特定组件集合的内部依赖性；
具体接口和实现解决的具体问题；
现有可替代解决方案的可用性分析；
本项目已提供的设计和实现的局限性。

@1.4 内联可行性研究：
基于现有经验，本项目中每个顶级子项目都假定可行，在设计以外产生空输出。
其它内容参见([Documentation::ProjectRules @@4.3]) 。

@2 设计：
本章的设计指项目层次上的整体设计规范。
具体组件集合和接口的设计参见对应的具体文档。

@2.1 表现原则：

@2.1.1 规约视角：
仅向内廪语义耦合：使用列举外延定义概念前必须提取清晰的内涵，同时避免和其它概念的耦合。
避免重复冗余：语义允许忽略差异的应保持同一性(identity) 的概念和实体不应存在别名以外的副本。

@2.1.2 组件视角：
层次封装：组件可分为若干层次，在任意层次上都需要保持对满足一定接口约束的同类组件的可替换性（如果可能，也适用于库的外部依赖项）。
任务关联：允许对完成一种任务提供多种接口，但应尽量能在足够明确的限制条件下找到单一最佳实践。

@2.1.3 用户视角：
给用户提供选择的自由。
信任用户，给用户提供服务而不是检查用户的行为。（类似 C 和 C++ 的设计哲学。注意这点同时也允许未定义行为。）

@2.2 模型：
表现以下设计意义：
环境隔离：对特定领域相关的上层源代码提供一致的接口。
抽象和封装：提供控制流实体语义的抽象；提供用于封装上层平台相关的模块的支持。

@2.2.1 组织概念：

@2.2.1.1 平台无关的组织分类：
框架核心称为 Core ；
其它必须直接基于 Core 之上一些外围功能实现程序是 Shell ；
和框架核心之间没有整体依赖性（依赖在逻辑上可被其它组件替代）的部分称为 Service 。
Shell 和 Core 应保持相对独立，以方便移植。

@2.2.1.1.1 相对性：
Shell 和 Core 的关系是相对的，例如：
操作系统上层（最终）用户界面和服务相对操作系统内核(kernel) ；
基于操作系统 Shell 的应用程序相对操作系统 Shell 。
这样， Shell 和 Core 之间的相对关系可以级联。对组织虚拟化程序架构等有一定意义。

@2.3 构建原则：
基本内容参见 [Documentation::CommonRules @@2.2] 。

@2.3.1 可移植性相关：
基本内容参见 [Documentation::CommonRules @@2.2.2] 。
语言使用规则参见 [Documentation::LanguageConvention @@5] 。
YSLib 的源代码的本体([Documentation::YFramework @@2.1]) 是平台中立([Documentation::CommonRules @@2.2.2.1]) 的。
其中的一部分在冯·诺依曼体系结构的现代数字式电子计算机的范畴内是平台无关的。

@2.3.1.1 实现要求：
依赖的语言实现要求参见 https://bitbucket.org/FrankHB/yslib/wiki/Development.zh-CN.md 。
实际使用的具体语言实现参见 @5.2 。

@2.3.1.2 平台模拟支持：
概念参见 https://bitbucket.org/FrankHB/yslib/wiki/Development.zh-CN.md  。
库提供程序模拟的接口（一般是 API ，也可以是 UI 等）支持平台模拟，包括以下形式：
平台中立([Documentation::CommonRules @@2.2.2.1]) 接口：适合所有平台但针对不同平台指定不同的行为实现。
非平台中立接口：适合特定的平台，不保证平台中立。
平台中立接口通过提供额外信息指定支持的平台（如在调用 API 时传递标识平台的参数）以实现不同目标平台上的相似功能接口。
非平台中立接口的 API 若仅适合特定的已知平台，在平台扩展([Documentation::ProjectRules @@3.3]) 提供。

@2.3.2 环境依赖性：
关于环境，参见 [Documentation::CommonRules @@2.2.2] 。
关于库配置，参见 @5 。
关于语言特性使用，参见 [Documentation::ProjectRules @@ 1.2.1] 。
YSLib 基于基本的底层系统接口（由 YFramework/YCLib[Documentation::YCLib] 支持）。

@2.3.2.1 文本编码：
和环境交互的外部编码默认 UTF-8 ，按需检查 BOM 。库的接口和实现使用的内部编码以本节规则决定。
必要时的转换编码或保证成功转换时未被文档另行约定的隐式行为一致的特定平台的实现。

@2.3.2.2 二进制互操作：
格式化输出及结构对齐时注意平台字长差异。

@2.3.3 可维护性和架构设计：
基本内容参见 [Documentation::CommonRules @@2.2.3] 。
语义相关的架构参见 [Documentation::CommonRules @@2.3.2] 。

@2.3.4 实现功能特征概述：
便于扩展。
尽可能地平台无关，且注重效率。
能够保持必要的运行时安全性。
实现一部分的通用较高级功能，例如消息机制(@2.4.1.3) 。

@2.3.5 参考标准和规格说明：
基本内容参见 [Documentation::CommonRules @@1.1] 。
语言使用另见 @1.3.2.1 。
遵从的其它标准和规格说明：
暂略。

@2.3.6 目标代码兼容性：
基本内容参见 [Documentation::CommonRules @@2.2.4] 。
关于开发和测试版本判断依赖开发阶段的定义，参见 [Documentation::ProjectRules @@2] 。
除非顶级子项目([Documentation::ProjectRules @@1.3]) 的文档另行约定， YSLib 项目不依赖具体体系结构和不同语言实现之间的互操作性。

@2.3.6.1 默认二进制依赖策略：
整个项目中，任意组件在相同平台配置的二进制兼容性保证由以下规则决定。
对明确具有二进制依赖的外部库和语言实现的([Documentation::Dependencies @@1]) 变更导致无法保证二进制兼容性时，无二进制兼容保证；
否则，对于未更改的库的模块([Documentation::ProjectRules @@3.2]) ，应保证双向兼容；
否则，对于非开发和测试版本之间，应提供符合文档约定的兼容性；
否则，若顶级子项目存在约定，使用此约定提供的最强兼容性；
否则，无二进制兼容保证。
注意，库中的定义是否声明为 inline （而不是实际内联）影响二进制兼容性。

@2.4 文本文件形式：
基本规则参见 https://bitbucket.org/FrankHB/yslib/wiki/WikiRules.en-US.md 。
因 DrMemory 不支持 BOM 所以使用的文件省略 BOM 。

@3 API 设计和风格概述：
基本规则参见 [Documentation::CommonRules @@3] 。

@3.1 类 C 标准库接口：

@3.1.1 内存管理行为：
接口不符合无隐式 malloc 规则 [Documentation::LanguageConvention @@5.25.3.1] 时必须向用户明确存储所有权。

@3.2 C++ 函数和函数模板：

@3.2.1 成员最小接口：
为了利用以类为单位的封装性（包括访问权限控制），一般类内的成员函数以最小接口为主，而人本接口在类外紧接类定义声明为第一个参数为类的引用类型的非成员函数。
可以适当使用友元简化接口和实现。

@3.2.2 函数参数和返回类型：
尽量使用返回值而不是输出参数传递结果，特别是在最小接口中。
合理使用默认函数参数减少需要的函数重载版本。
参数和返回类型选取规则参见 [Documentation::ProjectRules @@5.12.2] 。

@3.2.3 模板参数：
合理使用 ISO C++11 支持的函数模板的模板默认参数简化实现，减少需要的函数重载版本。

@3.3 错误处理：
基本内容参见 [Documentation::CommonRules @@3] 。

@3.3.1 异常消息：
使用仅使用基本字符集的字符串表示用户可读的消息。
除非必要，消息中不出现表示代码位置（例如所在函数）的信息，以免冗余。

@3.3.2 SFINAE(substition failure is not an error) 技巧：
使用 SFINAE 进行类型检查，实现复杂的重载匹配。避免暴露过于复杂的接口。
在模板参数或函数参数中使用 ISO C++11 的 std::enable_if 实现 SFINAE 。需要考虑函数签名时，只能使用前者；需要考虑模板和非模板的匹配顺序时，一般使用后者。

@4 标识符命名规约(naming convention) ：
以下是 YSLib 项目中标识符的命名规则和约定。

@4.1 通用指引：
参见 [Documentation::CommonRules @@4.1] 。

@4.1.1 保留标识符命名：
保留标识符基本内容参见 [Documentation::CommonRules @@4.1.6] 。
库保留的标识符参见 [Documentation::Defitioan] 。
除此之外，以下规则指定保留的命名规则，不引起歧义时，可被用户程序共享。

@4.1.1.1
以 "INC_" 和 "Inc_" 起始的标识符专用于头文件包含标识（参见 [Documentation::Definitions] ）。

@4.1.1.2 模板形式参数前缀：
除可与用户定义的字面量后缀以及非全局命名空间作用域的元函数或占位符重名，以下前缀保留给的标识符保留作为库和用户代码的模板形式参数的名称（模板参数引用作为函数参数时可以是对应的对象类型引用）：
"_b" ：布尔类型参数，包括内建 bool 类型的值或用于表示布尔值的 std::integral_constant 的实例（注意 value 成员不保证是 bool 类型）；
"_c" ：表示概念(concept) 的类型参数；
"_f" ：可调用类型(callable type) （可能是函数对象类型或成员指针）或作为元函数的类型参数；
"_i" ：接口（纯虚类）类型参数；
"_p" ：内建指针类型参数；
"_r" ：引用类型参数；
"_t" ：不包含在以上用法内的其它类型参数；
"_g" ：泛型类型（模板）参数，可能是元函数；
"_gi" ：泛型接口（纯虚类模板）参数；
"_gf" ：泛型函数/仿函数模板参数；
"_v" ：其它非类型参数（值参数）。

@4.1.2 惯用函数命名：
基本内容参见 [Documentation::CommonRules @@4.1.7] 。
若在同一个作用域中出现多个不同的以下约定相同类别内的名称，可以后缀正整数以示区分。

@4.1.2.1 YBase 和 YFramework 约定：
用于实现标准库兼容接口时，优先使用以下名称的对应或一致形式。
使用以下固定含义的模板形式参数名称（前缀参见 @4.1.1.2 ），同时表示对应的类型要求（模板参数引用作为函数参数时可以是对应的对象类型引用）：
_type ：一般类型参数（对应标准库的 T ）；
_type2 ：第二类型参数（对应标准库的 U ）；
_bCond ：表示选择结果的条件的 bool 参数。
_tElem ：元素类型（如 std::initializer_list 的模板参数等，对应标准库的 E ）；
_tEx ：异常类型（除非另行约定，应为类类型）；
_tSeq ：表示序列的类型参数（一般需要是类类型；注意可以是元类型的实例，而不一定是容器类型）。
_tScalar ：纯量类型（和向量类型相对；注意不一定是 ISO C++ 定义的纯量类型，即不需要保证满足 std::is_scalar 类型特征）；
_func ：函数对象类型；
_fCallable ：可调用类型；
_fPred ：谓词函数类型；
_fBiPred ：二元谓词函数类型；
_tIter ：迭代器类型；
_tIn ：输入迭代器类型；
_tOut ：输出迭代器类型；
_tFwd ：前向迭代器类型；
_tBi ：双向迭代器类型；
_tRandom ：随机访问迭代器类型；
_tRange ：一般范围类型；
_tCon ：容器类型（符合 ISO C++11 约定的容器要求的类型，或类似的在特定上下文中通过文档约定的类型如 std::string ，下同）；
_tSeqCon ：序列容器类型；
_tAssocCon ：关联容器和无序关联容器类型；
_tChar ：适合作为 std::char_traits 的第一参数的字符类型。
以上非数字结尾的类型参数加后缀 s 表示可变模板参数中的多个类型。
使用以下非 ISO C++11 的要求中出现的其它成员名称：
clone ：动态复制函数，返回类型为被复制的对象的指针。
begin 和 end 以 ADL 为使用形式，一般使用命名空间作用域包装，不作为 YFramework 类的成员名称。
无歧义时，优先使用约定的对象或对象引用类型的参数名称：
c 一般范围；
c 字符（特别是符合 _tChar 类型的）；
c 范围（特别是和容器并列时）；
con 容器（特别是符合 _tCon 、 _tSeqCon 或 _tAssocCon 类型或其引用类型的）；
il std::initializer_list 示例类型的参数（和标准库一致）；
str 字符串（字符指针或类）类型。

@4.1.2.2 YFramework 约定：

@4.1.2.2.1 模式 Fetch* ：
除了 YSLib 中非本体部分，命名空间作用域函数名 Fetch* ：语义近似于 Get*Of ，但遵循以下附加规则：
函数名符合模式 Fetch*Ref 的，返回类型为目标类型的引用或 const 引用类型；
函数名符合模式 Fetch*Ptr 的，返回类型为目标类型的指针、 const 指针或对应的智能指针类型；
目标类型为 POD 类型的，返回类型为目标类型；
其它情况返回类型为目标类型的引用或 const 引用类型。

@4.1.2.2.2 模式 Make* ：
类似 ISO C++ 标准库中的 make_* 。

@4.2 宏名：
基本内容参见 [Documentation::CommonRules @@4.2] 。

代码生成器：用宏展开为一段声明或定义的代码。

@4.2.3 全局保留宏名：
使用 YSLib 前需要保证未定义，且之后无法使用，除非使用 #undef 取消定义。
YSLib 保留宏名以 "YSL" 起始，其基础库使用保留宏名以 "YCL" 起始。

@4.2.4 局部保留宏名：
使用 YSLib 前需要保证未定义，但库实现使用 #undef 限制作用域，因此之后可以使用。
"This" 和 "CThis" 被保留。

@4.3 类型名：
参见 [Documentation::CommonRules @@4.3] 。

@4.4 标号：
参见 [Documentation::CommonRules @@4.4] 。

@4.5 函数名：
参见 [Documentation::CommonRules @@4.5] 。

@4.6 具名对象：
参见 [Documentation::CommonRules @@4.6] 。

@5 程序部署和用户配置：
依赖项相关定义参见 [Documentation::ProjectRules @@1] 。
项目管理相关定义参见 [Documentation::ProjectRules @@2] 。
本章描述 YSLib 项目中除了 YFramework/YSLib 以外的依赖项。
YSLib 项目的依赖项都是库，其中一部分是不由 YSLib 项目维护的第三方的外部依赖项。
外部依赖项中，系统库（ system library ，符合 GNU GPL v2 和 v3 条例定义）在平台配置中描述，可被所有非外部依赖项。
其它外部依赖项都被 YFramework 引用，如 FreeType2(@5.4.1) 。
以下除非另行约定，非外部依赖项的根路径取 YFramework 包含目录或源代码目录。

@5.1 平台配置：
关于平台的详细含义参见 [Documentation::ProjectRules @@1.2] 。
和本机语言实现相关的平台环境可使用经典系统类型名称(canonical system type name) 描述： architecture/vendor/OS/C library 四元组或 architecture/vendor/OS 三元组，除第一项外可能省略。
使用的实现（参见 @5.2 ）不和平台环境一一对应。一个平台环境可能有多个实现。
目标平台配置和 YCLib 平台定义文件([Documentation::YCLib @@5.1]) 中定义的公共平台对应。

@5.1.1 配置管理：
基本配置管理参见 [Documentation::ProjectRules @@2.1]。
MinGW32 为 DLL 目标追加对应 debug 和 release 的配置 debug_DLL 和 release_DLL 。

@5.1.2 当前正式支持的目标平台：
非宿主实现目标平台 DS （ Nintendo/iQue DS/DS Lite/DSi/DSi LL 以及 PC 端模拟器 DeSmuMe 等，对应系统名 arm-eabi 或 arm-none-eabi ）。
宿主实现目标平台 MinGW32 （对应系统名 i686-pc-mingw32 及其向前兼容的 i686-w64-mingw32 等）。
保证 MinGW-W64 的运行时可以正常构建。
使用 MinGW.org 的运行时自 b465 起支持。

@5.1.3 当前试验支持或不完全支持的目标平台：
当前试验支持宿主实现目标平台 Android （至少需 API Level 9 ）。
不添加其它代码，试验支持 x86_64-w64-mingw32 目标平台。

@5.1.4 平台限制：
当前 DS 仅使用静态链接库链接至目标。
当前 Android 不支持使用 Java 语言构建（ Makefile 缺少命令）；且仅支持单一动态库（ NativeActivity 限制）。

@5.2 环境实现：
外部依赖项参见 [Documentation::Dependencies @@1] 。
ISO C++ 实现定义行为要求满足 [Documentation::Dependencies @@1.1] 。
除了 ISO C++ 标准库外的非外部依赖项：
基于标准库的基础库 YBase([Documentation::YBase]) ，包含基于标准库的平台中立的扩展 YStandardEx 等，独立于 YFramework 。
基于 YBase 的平台隔离用库 YCLib([Documentation::YCLib]) ，包含于 YFramework 中。
平台工具链和标准库实现：
Windows 构建宿主公共环境参见 [Documentation::Dependencies @@1.3] 。
DS 平台参见 [Documentation::Dependencies @@1.4] 。
MinGW32 平台参见 [Documentation::Dependencies @@1.5] 。
Android 平台参见 [Documentation::Dependencies @@1.6] 。

@5.2.1 YBase ：
参见 [Documentation::YBase] 和 [Documentation::Dependencies @@1.2] 。

@5.2.2 YCLib ：
参见 [Documentation::YCLib] 。

@5.3 通用库：

@5.3.1 Loki ：
参见 [Documentation::Dependencies @@2.1] 。

@5.4 专用库：
包含于 YFramework 中的子库。
关于 CHRLib ，参见 [Documentation::YFramework @@2.7] 。
关于 Helper ，参见 [Documentation::YFramework @@2.8] 。
关于 NPL ，参见 [Documentation::YFramework @@2.9] 和 [Documentation::NPL]。
以下为第三方专用库（包含部分修改）：
FreeType 2 参见 [Documentation::Dependencies @@2.2] 。
Anti-Grain Geometry 参见 [Documentation::Dependencies @@2.3] 。
FreeImage 参见 [Documentation::Dependencies @@2.4] 。

@5.5 库基础结构：
平台设置在 YCLib::Platform([Documentation::YCLib @@ 5.1]) 中。
除了 MinGW32 的平台运行时外，所有外部链接库为静态库。除了 YCLib 外，对外部库未经过封装的使用仅在 Adaptor 中。这样有利于以子库为单位的移植。

@5.6 全局命名空间：
基本规则参见 [Documentation::ProjectRules @@3.5] 。
除了使用标准库命名空间 std 外如下所列。

@5.6.1 标准库实现提供的附加命名空间：
__gnu_cxx ： libstdc++ 扩展，可被 YBase::LibDefect 和 YFramework::YSLib::Adaptor 使用。

@5.6.2 YBase 引入的命名空间：
YBase 引入的主要命名空间唯一且和次级子项目的模块名称一致（但 YDefinition 此处同 YStandardEx ）。
ystdex ：从 std 扩充的平台无关的实用程序 YStandard 。 YSLib 本体直接依赖此命名空间。
ytest ：测试框架设施 YTest 。

@5.6.3 YFramework 引入的命名空间：
参见 [Documentation::YFramework @@2.3.4] 。

@6 编码风格导引：
仅叙述之前章节未涉及的内容。
基本内容参见 [Documentation::CommonRules @@5] 。

@6.1 源代码嵌入文档：
使用 Doxygen 。
编码适应大多数源文件，默认为 UTF-8 。
默认语言为简体中文（在接口文档中使用；实现中的注释默认使用美式英文）。

@6.1.1 注释风格：
使用简化的（去除可以省略的星号后的） Qt 风格的注释。
分行例外（默认参见 [Documentation::CommonRules @@5.4.1] ）： URL 链接等超出默认行宽时可在同一行（以避免无法生成正确的代码）。

@6.1.2 指令同义词：
当多种指令等价时使用 Doxygen 手册中直接说明（而非指示同义词即 "Equivalent to" ）的一项。
例外：
对外部参考使用 \see 而不是 \sa ；
\throw 指通过 throw 表达式或调用 throw 的专用助手例程显式抛出确定类型的异常， \exception 指内部调用间接抛出的可被特定异常处理器捕获的异常（可能为派生类）。

@6.1.3 指令行风格：
组(group) 相关指令（ \defgroup 、 \ingroup 、 \name 等）、实体标识指令（ \def 、 \fn 等）以及 \author 、\par 、 \relates 、 \sa 、 \since 、 \version 不使用句为单位（不使用全角标点）；其它指令后的内容以句为单位（对中文注释以全角标点结束；不成句的不视为完整的注释）。
\defgroup 指令在所有文件中应保持无歧义地出现一次以避免错误。
\par 指令以半角“:”结尾。
\sa 指定的名称在注释出现的声明区域按 ISO C++ 规则进行名称查找，同时使用 ADL 相关规则([Documentation::LanguageConvention @@5.3.3.1]) 。
实体注释中详细注释放在最后，和之前的指令相隔一个空行。

@6.1.4 指令格式和顺序：
组相关指令在最前（且对 \defgroup ，跟随注释首行“*”后使用一个水平制表符分隔），然后依次为实体标识指令（除了 \def ，一般省略）和其它指令。
指定顺序的段落指令： \brief 、 \tparam 、 \param 、 \pre 、 \post 、 \invariant 、 \return 、 \exception 、 \throw 、 \note 、 \warning 、 \bug 、 \deprecated 、 \relates 、 \sa 、 \see 、 \since  、 \todo 、 \par 。
对连续的 \tparam 和 \param 指令，相同指令按参数在参数列表中出现的顺序排序；对连续的 \throw 和 \exception 指令，相同指令按异常类型名排序。
从属的非段落指令如 \code 、 \endcode 、\tt 、 \verbatim 等不限制顺序。
其它顺序参见 https://www.drupal.org/node/1354#order 未和以上规则冲突的部分。

@6.1.5 组(grouping) ：
仅在必要时使用分组指令。
使用单行的分组边界，但不在注释块内使用等价的标记。
不使用 DISTRIBUTE_GROUP_DOC 。
当前 Doxygen 不支持嵌套成员分组。这是已知的待解决问题。

@6.2 实现语用规则：

@6.2.1 编码风格：
依次以部件、事件和调用形式的顺序集中添加或移除事件处理器，其中调用形式约定为操作符调用、成员函数调用和非成员函数调用；使用宽松分行([Documentation::CommonRules @@5.4.3.1]) 分隔处理器列表项。

@6.2.2 替代语言特性：
除非补充语言实现或类似场合的兼容性需要，为了使代码意图更明确且实现更简洁，考虑以下规则：
尽量使用智能指针([Documentation::LanguageConvention @@5.15.9]) 而不是 new-expression 和 delete-expression 管理资源，除非实现智能指针或另有约定。
显式转换：基本规则参见 [Documentation::LanguageConvention @@5.11.3] ；尽量使用 YBase::YStandardEx::TypePun(@2.4.4.2) 和 YBase::YStandardEx::Cast(@2.4.7.1) 中的转换模板代替内建显式转换。
使用 ystdex::retry_on_cond 代替 do-while （特别是每次迭代都更新最后需要返回的值的）循环，避免不必要的中间变量。

@6.2.3 限定名称：
在建议 [Documentation::LanguageConvention @@5.3.3.1] 的基础上强制要求全局名称保留前缀 :: 规则。
全局 operator new/delete 使用前缀 :: 以强调确定使用全局版本（对应非名称的 new/delete 表达式也同样使用）。
SFINAE(@3.3.2) 的需要以外的其它一般全局名称的使用总是保留前缀 :: 以便移植。
同理，除非另有约定，所有外部平台基础库不使用 using namespace 省略前缀命名空间的调用，同时保持和全局名称不省略 :: 的形式一致。
推论：包含使全局名称和不省略 :: 形式不一致的声明的头文件不能在其它作用域中使用。这已被 ISO C++ [using.headers] 涵盖，遵守 [Documentation::LanguageConvention @@5.15.2] 。

@6.2.4 限制使用标识符：
项目全局范围内以下 C++ 关键字应尽量少使用，考虑是否合理的替代：
new
delete
reinterpret_cast
参见 @6.2.2 。
关于 new 的例外，另见 [Documentation::LanguageConvention @@5.15.9.2] 。

@6.2.5 宏定义：
除非文档约定，不在代码中定义或取消定义影响实现特性的宏([Documentation::LanguageConvention @@5.3.5.2]) 。
不假定这些宏之前未被外部环境预定义([Documentation::LanguageConvention @@5.3.6]) ，且需保证在标准库头之前包含([Documentation::LanguageConvention @@5.3.9]) 。

@7 一般实现导引：
自定义应用程序 Shell 类，继承默认 Shells::Shell 类或其派生类并产生实例。
完成自定义 Shell 类的消息处理过程。一般把多个处理过程的响应封装为单一函数。
对支持实现对应 Shell 的窗口封装为窗体（Form）类（一般继承自 Window 类），在此自定义类中添加所需的 GUI 部件的定义，并实现界面效果。
在响应输入等事件消息的处理过程中添加对应的代码。

@7.1 初始化：
需要保证主 Shell 句柄在应用程序实例初始化之后初始化，基类 Shell 的构造函数调用了 Application 的非静态成员函数。

*/
////

