提交 7427bfa5 编写于 作者: zyjhandsome's avatar zyjhandsome

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

Signed-off-by: zyjhandsome's avatarzyjhandsome <zyjhandsome@126.com>
上级 99c9d6c4
......@@ -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地址
......
# 文档示例代码风格
本文参考了业界的标准规范和最佳实践,旨在提高文档示例代码的可读性、可维护性,以及风格一致性,以增强开发者的使用体验。
本文旨在为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)
### 【规则】代码格式化
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册