!19320 贡献文档 > 文档风格中，新增“示例代码风格”

Merge pull request !19320 from zyjhandsome/master

zh-cn/application-dev/application-models/process-model-stage.md

@@ -4,10 +4,8 @@
 OpenHarmony的进程模型如下图所示。
 
 
-- 应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility、DataShareExtensionAbility运行在同一个独立进程中，如下图中绿色部分的“Main Process”。
-
-- 应用中（同一Bundle名称）的同一类型ExtensionAbility（除ServiceExtensionAbility和DataShareExtensionAbility外）运行在一个独立进程中，如下图中蓝色部分的“FormExtensionAbility Process”、“InputMethodExtensionAbility Process”、其他ExtensionAbility Process。
-
+- 应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility和DataShareExtensionAbility均是运行在同一个独立进程（主进程）中，如下图中绿色部分的“Main Process”。
+- 应用中（同一Bundle名称）的所有同一类型ExtensionAbility（除ServiceExtensionAbility和DataShareExtensionAbility外）均是运行在一个独立进程中，如下图中蓝色部分的“FormExtensionAbility Process”、“InputMethodExtensionAbility Process”、其他ExtensionAbility Process。
 - WebView拥有独立的渲染进程，如下图中黄色部分的“Render Process”。
 
 

zh-cn/application-dev/application-models/thread-model-stage.md

@@ -4,7 +4,7 @@
 
 1. 执行UI绘制。
 2. 管理主线程的ArkTS引擎实例，使多个UIAbility组件能够运行在其之上。
-3. 管理其他线程（例如Worker线程）的ArkTS引擎实例，例如启动和终止其他线程。
+3. 管理其他线程的ArkTS引擎实例，例如启动和终止Worker线程。
 4. 分发交互事件。
 5. 处理应用代码的回调，包括事件处理和生命周期管理。
 6. 接收Worker线程发送的消息。

zh-cn/application-dev/quick-start/multi-hap-principles.md

@@ -4,7 +4,7 @@
 多HAP机制主要是为方便开发者进行模块化管理。HAP和应用运行时的进程并不是一一对应的，具体运行机制如下：
 
 
-- 默认情况下，应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility、DataShareExtensionAbility运行在同一个独立进程中，其他同类型ExtensionAbility分别运行在单独的进程。
+- 默认情况下，应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility和DataShareExtensionAbility均是运行在同一个独立进程（主进程）中，而其他相同类型的ExtensionAbility则是运行在各自独立的进程中。
 
 - HAP支持在module.json5（Stage模型）或者config.json（FA模型）中通过process标签配置单独的进程（仅系统应用支持，三方应用不支持）。配置了process的HAP，其组件运行在单独的process进程中，多个HAP可以配置相同的process，则这些HAP运行在相同进程中，process配置的详细说明请参见[module.json5配置文件](module-configuration-file.md)。
 

zh-cn/contribute/style-guide/Readme-CN.md

@@ -4,3 +4,4 @@
 - [语言风格](style-guide-language-style.md)
 - [文档结构](style-guide-document-structure.md)
 - [内容元素](style-guide-content-elements.md)
+- [示例代码风格](style-guide-example-code-style.md)

zh-cn/contribute/style-guide/style-guide-content-elements.md

@@ -81,7 +81,7 @@
 
 ### 绘图
 
-【规则】绘图中出现的英文单词大小写规则：术语、缩略语、专有名词（如开发板名称、设备名称）遵循[术语与缩略语](#%E6%9C%AF%E8%AF%AD%E5%8F%8A%E7%BC%A9%E7%95%A5%E8%AF%AD)的要求，全文统一大小写；其它英文单词遵循Sentence caps样式，即首个单词首字母大写。
+【规则】绘图中出现的英文单词大小写规则：术语、缩略语、专有名词（如开发板名称、设备名称）遵循[术语及缩略语](#术语及缩略语)的要求，全文统一大小写；其它英文单词遵循Sentence caps样式，即首个单词首字母大写。
 
 【建议】字号：中英文正常字号均采用10.5pt（14px）。中文字号下限为9pt（12px），英文字号下限为8pt（11px）。
 
@@ -156,16 +156,16 @@
 
 - 链接到其他站点：\[示例]\(www.example.com)
 
-  | **正例** | **反例** |
-  | -------- | -------- |
+  | **正例**                                                    | **反例**                                               |
+  | ----------------------------------------------------------- | ------------------------------------------------------ |
   | 请参见\[OpenHarmony开源项目](https://gitee.com/openharmony) | OpenHarmony开源项目请参见https://gitee.com/openharmony |
 
 
 ## 术语及缩略语
 
-【规则】术语/缩略语名称要同“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”保持一致，且全文统一。
+【规则】术语/缩略语名称要同“[OpenHarmony术语表](../../glossary.md)”保持一致，且全文统一。
 
-【规则】对于“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”中未涵盖的行业通用术语/缩略语（如IP，MAC等），要同国际、国家、行业标准中的名称保持一致。
+【规则】对于“[OpenHarmony术语表](../../glossary.md)”中未涵盖的行业通用术语/缩略语（如IP，MAC等），要同国际、国家、行业标准中的名称保持一致。
 
 【规则】禁止随意缩写英文单词，自创缩略语。
 
@@ -173,7 +173,7 @@
 
 【规则】中文文档中，缩略语全称中对应的字母大写。
 
-【规则】“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”中，术语名以“英文全称 (缩略语)；中文全称”的形式写作；术语解释直接陈述术语内涵，不需要重复术语名。
+【规则】“[OpenHarmony术语表](../../glossary.md)”中，术语名以“英文全称 (缩略语)；中文全称”的形式写作；术语解释直接陈述术语内涵，不需要重复术语名。
 
 | **正例**                                                     | **反例**                                                     |
 | ------------------------------------------------------------ | ------------------------------------------------------------ |
@@ -315,40 +315,7 @@
 
 ## 代码与注释
 
-
-### 行内代码
-
-【规则】对于正文描述中涉及代码的内容，比如实际代码中的方法名、参数名或代码文件名等，使用`包裹显示。
-
-| 正例 | 反例 |
-| -------- | -------- |
-| 在`index.js`文件中实现页面跳转。 | 在index.js文件中实现页面跳转。 |
-
-
-### 代码块
-
-【规则】对代码示例、命令行使用代码样式。在Markdown中，使用```呈现代码样式，同时指定语言类型。
-
-![代码块示例](figures/code-block-example.png)
-
-【规则】代码块内容应符合对应语言的通用编程规范。
-
-【规则】完整举例中的代码块复制后可直接执行，且执行结果与文档描述一致。
-
-【规则】如果代码块中没有标识行号，则不添加行号标识。
-
-【规则】代码块显示符合缩进要求。
-
-【建议】代码块中的关键代码段提供注释说明。
-
-
-### 注释
-
-【规则】适时为代码块添加注释，特别是有解释说明、开发建议或注意事项的位置。恰当的注释可有效提升代码块可读性，帮助开发者快速掌握开发过程。
-
-【规则】注释符与代码块语法保持一致，禁止自创注释符。注释符与注释内容间统一添加一个空格。例如：对于JavaScript代码块，注释写法为“// 注释内容”。
-
-【规则】当一行注释内容过长时，注意断句切分到下一行呈现。
+请参见[示例代码风格](style-guide-example-code-style.md)。
 
 
 ## IP及MAC地址

zh-cn/contribute/style-guide/style-guide-example-code-style.md

+# 示例代码风格
+本规范适用于文档中ArkTS、JavaScript和C/C++等编程语言的示例代码片段，旨在提高OpenHarmony文档示例代码的可读性、可维护性，以及风格一致性。
+
+## 代码规范
+
+### 【规则】遵守基本编程规范
+
+【描述】
+
+文档的示例代码需要遵循[JavaScript语言编程规范](../OpenHarmony-JavaScript-coding-style-guide.md)、[C语言编程规范](../OpenHarmony-c-coding-style-guide.md)和[C++语言编程规范](../OpenHarmony-cpp-coding-style-guide.md)基本的编码规范，包括命名规范、代码格式和代码规范等。
+
+### 【规则】每个接口（包括方法和组件）均需要提供示例代码
+
+【描述】
+
+API参考中，每个接口（包括方法和组件）均需要提供示例代码。如果多个API存在关联关系，则需要在一个场景化的代码示例中体现。
+
+### 【规则】示例代码中的变量需要包含定义、使用方法或者来源链接参考或者说明
+
+【描述】
+
+示例代码中的变量需要包含定义、使用方法或者来源链接参考或者说明，以确保开发者能够理解如何使用。例如，如果涉及到应用开发路径，需要提供获取应用开发路径的链接参考或方法。
+
+【正例】
+
+示例中的context的获取方式请参见[获取UIAbility的上下文信息](../../application-dev/application-models/uiability-usage.md#获取uiability的上下文信息)。
+
+```ts
+let context = ...; // UIAbilityContext
+let want = {
+  deviceId: '', // deviceId为空表示本设备
+  bundleName: 'com.example.myapplication',
+  abilityName: 'FuncAbility',
+  moduleName: 'func', // moduleName非必选
+  parameters: { // 自定义信息
+    info: '来自EntryAbility Index页面',
+  },
+}
+// context为调用方UIAbility的UIAbilityContext
+context.startAbilityForResult(want).then((data) => {
+  ...
+}).catch((err) => {
+  console.error(`Failed to start ability for result. Code is ${err.code}, message is ${err.message}`);
+})
+```
+
+【反例】
+
+```ts
+// 反例1：使用到的context和want变量未进行定义
+// context为调用方UIAbility的UIAbilityContext
+context.startAbilityForResult(want).then((data) => {
+  ...
+}).catch((err) => {
+  console.error(`Failed to start ability for result. Code is ${err.code}, message is ${err.message}`);
+})
+
+// 反例2：UIAbilityContext的使用来源不止this.context这一种，这里列举出来就会有展示不全的问题
+let context = this.context; // UIAbilityContext
+let want = {
+  deviceId: '', // deviceId为空表示本设备
+  bundleName: 'com.example.myapplication',
+  abilityName: 'FuncAbility',
+  moduleName: 'func', // moduleName非必选
+  parameters: { // 自定义信息
+    info: '来自EntryAbility Index页面',
+  },
+}
+// context为调用方UIAbility的UIAbilityContext
+context.startAbilityForResult(want).then((data) => {
+  ...
+}).catch((err) => {
+  console.error(`Failed to start ability for result. Code is ${err.code}, message is ${err.message}`);
+})
+```
+
+### 【建议】一致的依赖包命名风格
+
+【描述】
+
+导入的依赖包的命名与其依赖包的命名空间保持一致，以便于维护和理解代码。
+
+采用一致的依赖包命名风格还可以方便IDE进行提示导入，提高编码效率。
+
+【正例】
+
+```ts
+import promptAction from '@ohos.promptAction';
+```
+
+【反例】
+
+```ts
+// 包名和其命名空间不一致，不利于维护和理解代码
+import prompt from '@ohos.promptAction';
+```
+
+### 【规则】组件宽高等属性不加单位
+
+【描述】
+
+为了保持代码的一致性和简洁性，在设置组件的宽度、高度等属性时，应该尽量避免添加单位，因为组件的宽度、高度等属性默认以像素为单位。同时，避免添加单位也可以提高代码的可读性和便于维护。
+
+【正例】
+
+```ts
+Image('test.png')
+  .width(100)
+  .height(100)
+
+Text('Hello World')
+  .fontSize(50)
+```
+
+【反例】
+
+```ts
+Image('test.png')
+  .width('100vp')
+  .height('100vp')
+
+Text('Hello World')
+  .fontSize('50fp')
+```
+
+## 代码展示
+
+### 【规则】行内代码使用`包裹显示
+
+【描述】
+
+正文描述中涉及代码的内容，比如实际代码中的方法名、参数名或代码文件名等，使用`包裹显示。
+
+【正例】
+
+在`Index.ets`文件中实现页面跳转。
+
+【反例】
+
+在Index.ets文件中实现页面跳转。
+
+### 【规则】代码示例、命令行使用代码样式进行代码染色
+
+【描述】
+
+对代码示例、命令行使用代码样式。在Markdown中，使用```呈现代码样式，同时指定语言类型。
+
+代码染色是指在编辑器中对代码进行不同颜色的标记，以区分不同语法元素的功能。例如在编辑器中对不同的关键字、变量名、注释等使用不同的颜色进行标记，可以让代码更加易读易懂。
+
+![代码块示例](figures/code-block-example.png)
+
+### 【规则】代码格式化
+
+【描述】
+
+在将代码示例放入指南之前，使用DevEco Studio中的代码格式化功能对代码进行格式化，以确保代码的一致性和可读性。
+
+格式化代码的方法包括缩进、空格、换行等，这些方法可以使代码更易于阅读和理解，提高代码的可维护性和扩展性。
+
+【正例】
+
+```ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+import window from '@ohos.window';
+
+export default class EntryAbility extends UIAbility {
+  onWindowStageCreate(windowStage: window.WindowStage) {
+    windowStage.loadContent('pages/Index', (err, data) => {
+    });
+  }
+}
+```
+
+【反例】
+
+```ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+import window from '@ohos.window';
+
+export default class EntryAbility extends UIAbility {
+  onWindowStageCreate(windowStage: window.WindowStage) {
+    // 代码未格式化
+      windowStage.loadContent('pages/Index', (err, data) => {
+    });
+  }
+}
+```
+
+### 【规则】省略代码展示
+
+【描述】
+
+当需要在文档或代码中展示省略的部分时，使用统一的省略代码格式。省略代码应该简洁明了，避免冗长或混乱的格式。
+
+【正例】
+
+```ts
+// 正例1：
+...
+
+// 正例2：
+// To do sthing.
+```
+
+【反例】
+
+```ts
+// 反例1：
+// ...
+
+// 反例2：
+....
+
+// 反例3：
+......
+```
+
+### 【规则】代码注释展示
+
+【描述】
+
+示例代码中的关键内容和逻辑需要添加注释来说明，以确保开发者理解代码的作用。
+
+适时为代码块添加注释，特别是有解释说明、开发建议或注意事项的位置。恰当的注释可有效提升代码块可读性，帮助开发者快速掌握开发过程。
+
+注释符与代码块语法保持一致，禁止自创注释符。注释符与注释内容间统一添加一个空格。例如：对于ArkTS代码块，注释写法为“// 注释内容”。
+
+当一行注释内容过长时，注意断句切分到下一行呈现。
+
+示例代码中的关键内容和逻辑需要添加注释来说明，以确保开发者理解代码的作用。
+
+代码注释应该清晰、简洁、有用，能够方便别人理解代码的含义和作用。注释应该写在代码上方或右方。
+
+【正例】
+
+```ts
+// 正例1：
+// 定义生命周期回调对象
+let abilityLifecycleCallback = {};
+
+// 正例2：
+let abilityLifecycleCallback = {}; // 定义生命周期回调对象
+```
+
+【反例】
+
+```ts
+// 反例1：注释符与注释内容之间没有添加空格
+//定义生命周期回调对象
+let abilityLifecycleCallback = {};
+
+// 反例2：注释符与注释内容之间没有添加空格
+let abilityLifecycleCallback = {}; //定义生命周期回调对象
+
+// 反例3：注释符与注释内容之间添加了多个空格
+let abilityLifecycleCallback = {};       // 定义生命周期回调对象
+```
+
+## 异常处理
+
+### 【规则】在可能出现异常的代码段加上异常捕获，并按不同的异常类型进行分支判断
+
+【描述】
+
+在可能出现异常的代码段加上异常捕获，并按不同的异常类型进行分支判断，针对不同的异常类型需要使用统一的异常分支判断方式。
+
+【正例】
+
+```ts
+// 情形1：err为undefined的场景
+if (err) {
+  ...
+}
+
+// 情形2：err.code为非0的场景
+if (err.code) {
+  ...
+}
+```
+
+【反例】
+
+```ts
+// 反例1：
+if (err == null) {
+  ...
+}
+
+// 反例2：
+if (err != null) {
+  ...
+}
+
+// 反例3：
+if (err == undefined) {
+  ...
+}
+
+// 反例4：
+if (err === undefined) {
+  ...
+}
+
+// 反例5：
+if (err !== undefined) {
+  ...
+}
+```
+
+### 【规则】使用console.error输出异常的详细信息，包含错误码和相关的message信息
+
+【描述】
+
+当存在异常情况时，统一使用`console.error(...)`方法将异常信息打印到控制台，以便在调试时能够快速发现问题。
+
+在异常处理中，应该打印出异常的详细信息以便调试。
+
+在打印异常信息时，应该使用模板字符串，并标明异常信息的`code`和`message`参数。
+
+【正例】
+
+```ts
+// 模板：
+console.error(`Failed to do sthing. Code: ${err.code}, message: ${err.message}`);
+
+// 正例：
+notificationManager.publish(notificationRequest, (err) => {
+  if (err) {
+    // 异常分支打印
+    console.error(`Failed to publish notification. Code: ${err.code}, message: ${err.message}`);
+    return;
+  }
+  ...
+});
+```
+
+【反例】
+
+```ts
+// 反例1：错误日志使用console.log输出，不足以让开发者在调试时快速找到问题
+notificationManager.publish(notificationRequest, (err) => {
+  if (err) {
+    // 异常分支打印
+    console.log(`Failed to publish notification. Code: ${err.code}, message: ${err.message}`);
+    return;
+  }
+  ...
+});
+
+// 反例2：错误日志使用console.info输出，而非console.error，不利于开发者区分日志级别，快速找到问题
+notificationManager.publish(notificationRequest, (err) => {
+  if (err) {
+    // 异常分支打印
+    console.info(`Failed to publish notification. Code: ${err.code}, message: ${err.message}`);
+    return;
+  }
+  ...
+});
+
+// 反例3：异常信息缺乏具体的code和message参数，不利于开发者定位和解决问题
+console.error(`Failed to publish notification, err: ${err}`);
+
+// 反例4：使用单引号而非模板字符串的双引号，导致变量无法解析，输出的日志信息不正确
+console.error('Failed to publish notification, err: ${err}');
+
+// 反例5：使用字符串拼接和JSON序列化输出错误信息，不够直观和简洁，会增加日志产生量，不利于快速定位问题
+console.error('Failed to publish notification, err: ' + JSON.stringify(err));
+```
+
+## 日志打印
+
+### 【规则】正常日志打印使用console.info，以提供程序运行的状态和关键信息
+
+【描述】
+
+在代码编写过程中，为了更好地记录程序运行过程中的信息，开发者需要使用日志打印，以便于在程序出现异常时进行定位和排查。
+
+在正常情况下，使用`console.info(...)`来打印正常日志信息。
+
+【正例】
+
+```ts
+// 模板：
+console.info('Succeeded in doing sthing.');
+
+// 正例：
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.info('Succeeded in publishing notification.');
+});
+```
+
+【反例】
+
+```ts
+// 反例1：使用console.log(...)可能会让程序员产生困惑，无法明确该日志信息是正常日志还是错误日志
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.log('Succeeded in publishing notification.');
+});
+
+// 反例2：使用了console.error(...)而不是console.info(...)来打印正常日志信息。console.error通常用于打印错误信息，而不是正常的日志信息
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.error('Succeeded in publishing notification.');
+});
+```
+
+### 【规则】正常成功日志打印使用succeeded，以表示程序执行成功的结果
+
+【描述】
+
+在日志打印中使用一致的语言，例如成功日志可以使用`succeeded`来表达。
+
+【正例】
+
+```ts
+// 模板：
+console.info('Succeeded in doing sthing.');
+
+// 正例：
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.info('Succeeded in publishing.');
+});
+```
+
+【反例】
+
+```ts
+// 反例1：
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.info('Invoke publish success.');
+});
+
+// 反例2：
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.info('Invoke publish successful.');
+});
+
+// 反例3：
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.info('Invoke publish successfully.');
+});
+```
+
+## 代码逻辑
+
+### 【规则】回调方法中使用箭头函数替代常规函数
+
+【描述】
+
+在使用回调方法时，应该尽可能使用箭头方法代替常规方法，箭头方法的一个主要优点是可以避免 `this` 指向问题。在箭头方法中，`this` 绑定的是它所处的上下文的 `this` 值，而不是方法被调用时的 `this` 值。这样可以避免在使用常规方法时需要使用 `bind()` 或 `call()` 来绑定 `this` 的问题，从而简化代码并提高可读性。
+
+【正例】
+
+```ts
+notificationManager.publish(notificationRequest, (err) => {
+  ...
+  console.info('Invoke publish succeeded.');
+});
+```
+
+【反例】
+
+```ts
+notificationManager.publish(notificationRequest, function (err) {
+  ...
+  console.info('Invoke publish succeeded.');
+});
+```
+
+### 【规则】禁止使用废弃接口
+
+【描述】
+
+禁止使用废弃接口，因为他们可能会在未来的版本中被删除或更改。使用最新的接口可以确保代码的稳定性和可维护性。
+
+使用废弃接口可能导致代码不稳定，也可能会因为该接口在后续版本的更新中被废弃而引发编译错误、运行错误等问题。
+
+如果在后续的版本中废除了某些接口，所有依赖这些接口的示例代码都需要同步适配修改。
+
+【正例】
+
+```ts
+import fs from '@ohos.file.fs';
+
+function createFile() {
+  // 获取应用文件路径
+  let context = ...; // UIAbilityContext
+  let filesDir = context.filesDir;
+
+  // 新建并打开文件
+  let file = fs.openSync(filesDir + '/test.txt', fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
+  // 写入一段内容至文件
+  let writeLen = fs.writeSync(file.fd, 'Try to write str.');
+  // 从文件读取一段内容
+  let buf = new ArrayBuffer(1024);
+  let readLen = fs.readSync(file.fd, buf, { offset: 0 });
+  // 关闭文件
+  fs.closeSync(file);
+}
+```
+
+【反例】
+
+```ts
+// 使用了废弃的fileio接口，而不是推荐的fs接口
+import fileio from '@ohos.fileio';
+
+function createFile() {
+  // 获取应用文件路径
+  let context = ...; // UIAbilityContext
+  let filesDir = context.filesDir;
+
+  // 新建并打开文件
+  let fileFD = fileio.openSync(filesDir + '/test.txt', 0o102, 0o640);
+  // 写入一段内容至文件
+  let writeLen = fileio.writeSync(fileFD, 'Try to write str.');
+  // 从文件读取一段内容
+  let buf = new ArrayBuffer(1024);
+  let readLen = fileio.readSync(fileFD, buf, { offset: 0 });
+  // 关闭文件
+  fileio.closeSync(fileFD);
+}
+```
+