diff --git a/zh-cn/contribute/style-guide/style-guide-content-elements.md b/zh-cn/contribute/style-guide/style-guide-content-elements.md index 6e4df91da149ba948da02bdc58abdcb0630ffc6a..0db544a23007d85ea3da60d3607aba2728de42b8 100755 --- a/zh-cn/contribute/style-guide/style-guide-content-elements.md +++ b/zh-cn/contribute/style-guide/style-guide-content-elements.md @@ -156,8 +156,8 @@ - 链接到其他站点:\[示例]\(www.example.com) - | **正例** | **反例** | - | -------- | -------- | + | **正例** | **反例** | + | ----------------------------------------------------------- | ------------------------------------------------------ | | 请参见\[OpenHarmony开源项目](https://gitee.com/openharmony) | OpenHarmony开源项目请参见https://gitee.com/openharmony | @@ -315,40 +315,7 @@ ## 代码与注释 - -### 行内代码 - -【规则】对于正文描述中涉及代码的内容,比如实际代码中的方法名、参数名或代码文件名等,使用`包裹显示。 - -| 正例 | 反例 | -| -------- | -------- | -| 在`index.js`文件中实现页面跳转。 | 在index.js文件中实现页面跳转。 | - - -### 代码块 - -【规则】对代码示例、命令行使用代码样式。在Markdown中,使用```呈现代码样式,同时指定语言类型。 - -![代码块示例](figures/code-block-example.png) - -【规则】代码块内容应符合对应语言的通用编程规范。 - -【规则】完整举例中的代码块复制后可直接执行,且执行结果与文档描述一致。 - -【规则】如果代码块中没有标识行号,则不添加行号标识。 - -【规则】代码块显示符合缩进要求。 - -【建议】代码块中的关键代码段提供注释说明。 - - -### 注释 - -【规则】适时为代码块添加注释,特别是有解释说明、开发建议或注意事项的位置。恰当的注释可有效提升代码块可读性,帮助开发者快速掌握开发过程。 - -【规则】注释符与代码块语法保持一致,禁止自创注释符。注释符与注释内容间统一添加一个空格。例如:对于JavaScript代码块,注释写法为“// 注释内容”。 - -【规则】当一行注释内容过长时,注意断句切分到下一行呈现。 +请参见[示例代码风格](style-guide-example-code-style.md)。 ## IP及MAC地址 diff --git a/zh-cn/contribute/style-guide/style-guide-example-code-style.md b/zh-cn/contribute/style-guide/style-guide-example-code-style.md index c34f16cd81e39dc0f8b5bdcb8903388015f7b4d4..f84d43dd81fed01ff6385c349264cb3020e0bb09 100644 --- a/zh-cn/contribute/style-guide/style-guide-example-code-style.md +++ b/zh-cn/contribute/style-guide/style-guide-example-code-style.md @@ -1,7 +1,5 @@ -# 文档示例代码风格 -本文参考了业界的标准规范和最佳实践,旨在提高文档示例代码的可读性、可维护性,以及风格一致性,以增强开发者的使用体验。 - -本文旨在为OpenHarmony指南和API参考中的设计和内容作者提供示例代码风格指导。适用于包括ArkTS、JavaScript和C等编程语言的示例代码片段。 +# 示例代码风格 +本文参考了业界的标准规范和最佳实践,旨在提高OpenHarmony文档示例代码的可读性、可维护性,以及风格一致性,适用于包括ArkTS、JavaScript和C/C++等编程语言的示例代码片段。 ## 代码规范 @@ -9,7 +7,7 @@ 【描述】 -文档的示例代码需要遵循[JavaScript语言编程规范](../OpenHarmony-JavaScript-coding-style-guide.md)、[C语言编程规范](../OpenHarmony-c-coding-style-guide.md)基本的编码规范,包括命名规范、代码格式和代码规范等。 +文档的示例代码需要遵循[JavaScript语言编程规范](../OpenHarmony-JavaScript-coding-style-guide.md)、[C语言编程规范](../OpenHarmony-c-coding-style-guide.md)和[C++语言编程规范](../OpenHarmony-cpp-coding-style-guide.md)基本的编码规范,包括命名规范、代码格式和代码规范等。 ### 【规则】每个接口(包括方法和组件)均需要提供示例代码 @@ -149,47 +147,7 @@ Text('Hello World') 代码染色是指在编辑器中对代码进行不同颜色的标记,以区分不同语法元素的功能。例如在编辑器中对不同的关键字、变量名、注释等使用不同的颜色进行标记,可以让代码更加易读易懂。 -【正例】 - -```ts -let message: string = 'Hello World'; -console.info(message); -``` - -```json -{ - "module": { - ... - "abilities": [ - { - "launchType": "singleton", - ... - } - ] - } -} -``` - -【反例】 - -``` -let message: string = 'Hello World'; -console.info(message); -``` - -``` -{ - "module": { - ... - "abilities": [ - { - "launchType": "singleton", - ... - } - ] - } -} -``` +![代码块示例](figures/code-block-example.png) ### 【规则】代码格式化